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Notices 



References in this publication to IBM products, programs, or services do not 
imply that IBM intends to make these available in all countries in which IBM 
operates. Any reference to an IBM product, program, or service is not 
intended to state or imply that only that IBM product, program, or service 
may be used. Subject to IBM's valid intellectual property or other legally 
protectable rights, any functionally equivalent product, program, or service 
may be used instead of the IBM product, program, or service. The evaluation 
and verification of operation in conjunction with other products, except those 
expressly designated by IBM, are the responsibility of the user. 

IBM may have patents or pending patent applications covering subject matter 
in this document. The furnishing of this document does not give you any 
license to these patents. You can send license inquiries, in writing, to the IBM 
Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood 
NY 10594, U.S.A. 

Licensees of this program who wish to have information about it for the 
purpose of enabling: (i) the exchange of information between independently 
created programs and other programs (including this one) and (ii) the mutual 
use of the information which has been exchanged, should contact the SWS 
General Legal Counsel, IBM Corporation, Department TL3 Building 062, P. O. 
Box 12195, Research Triangle Park, NC 27709-2195. Such information may be 
available, subject to appropriate terms and conditions, including in some 
cases, payment of a fee. 

IBM has made reasonable efforts to ensure the accuracy of the information 
contained in this publication. If a softcopy of this publication is provided to 
you with the product, you should consider the information contained in the 
softcopy version the most recent and most accurate. However, this publication 
is presented "as is" and IBM makes no warranties of any kind with respect to 
the contents hereof, the products listed herein, or the completeness or 
accuracy of this publication. 

IBM may change this publication, the product described herein, or both. 
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• CICS for Windows NT refers to IBM TXSeries for Windows NT Version 4.2. 
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- CICS for Solaris system 

• DB2/VSE refers to SQL/DS Version 3 Release 4 or later. Any references to 
SQL/DS refer to DB2/VSE and SQL/DS on VM. In addition, any references 
to SQL/400 refer to DB2/400. 

• OS/2 CICS applies to CICS Operating System/2 (CICS for OS/2). 

• Workstation applies to a personal computer, not an AIX workstation. 

• The make process applies to the generic process not to specific make 
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• Unless otherwise noted, references to VM apply to Virtual 
Machine/ Enterprise Systems Architecture (VM/ESA) environments. 
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• DB2/2 applies to DB2/2 Version 2.1 or later, and DB2 Universal Database 
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• Unless a specific version of Windows NT is referenced, statements 
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Terminology differences between Java and Smalltalk 

VisualAge Generator Developer can be installed as a feature of VisualAge for 
Java or VisualAge Smalltalk. Where appropriate, the documentation uses 
terminology that is specific to Java or Smalltalk. But where the information is 
specific to VisualAge Generator and virtually the same for both environments, 
the Java/Smalltalk term is used. 



Table 1. Terminology differences between Java and Smalltalk 



Java term 


Combined Java/Smalltalk 
term 


Smalltalk term 


Project 


Project/ Configuration map 


Configuration map 


Package 


Package / Application 


Application 


Workspace 


Workspace / Image 


Image 


Beans palette 


Beans/Parts palette 


Parts palette 


Bean 


Visual part or bean 


Visual part 


Repository 


Repository/ENVY library 


ENVY library manager 


Options 


Options / Preferences 


Preferences 
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About this document 



Use this document to get step-by-step instructions for building, managing, 
and testing Visual Age Generator parts. The tasks covered here are also 
available from the online help and online books. 

How This Document Is Organized 

The tasks in this book are grouped by the kind of part to which they are 
related; for example, logic parts, data parts, user interfaces, and control parts. 
Other tasks cover library management basics and testing. Because some tasks 
are the same for different parts, using the index to find tasks is recommended 



Documentation provided with VisualAge Generator 

VisualAge Generator documents are provided in one or more of the following 
formats: 

• Printed and separately ordered using the individual form number. 

• Online book files (.pdf) on the product CD-ROM. Adobe Acrobat Reader is 
used to view the manuals online and to print desired pages. 

• HTML files (.htm) on the product CD-ROM and from the VisualAge 
Generator web page (http://www.ibm.com/software/ad/visgen). 

The following books are shipped with the VisualAge Generator Developer 
CD. Updates are available from the VisualAge Generator Web page. 

• VisualAge Generator Getting Started (GH23-0258-01) u 

• VisualAge Generator Installation Guide (GH23-0257-01) 1,2 

• Introducing VisualAge Generator Templates (GH23-0272-01) 2,3 

The following books are shipped in PDF and HTML formats on the VisualAge 
Generator CD. Updates are available from the VisualAge Generator Web page. 
Selected books are available in print as indicated. 

• VisualAge Generator Client/Server Communications Guide (SH23-0261-01) 1, 2 

• VisualAge Generator Design Guide (SH23-0264-00) 1 

• VisualAge Generator Generation Guide (SH23-0263-01) 1 



1. These documents are available as HTML files and PDF files on the product CD. 

2. These documents are available in hardcopy format. 

3. These documents are available as PDF files on the product CD. 

4. This document is included when you order the VisualAge Generator Server product CD. 
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• VisualAge Generator Messages and Problem Determination Guide 
(GH23-0260-01) 1 

• VisualAge Generator Programmer's Reference (SH23-0262-01) 1 

• VisualAge Generator Migration Guide (SH23-0267-00) 1 

• VisualAge Generator Server Guide for Workstation Platforms (SH23-0266-01) 1,4 

• VisualAge Generator System Development Guide (SG24-5467-00) 2 

• VisualAge Generator User's Guide (SH23-0268-01) 2 

• VisualAge Generator Web Transaction Development Guide (SH23-0281-00) 1 

The following documents are available in printed form for VisualAge 
Generator Server for AS / 400 and VisualAge Generator Server for MVS, VSE, 
and VM: 

• VisualAge Generator Server Guide for AS/400 (SH23-0280-00) 2 

• VisualAge Generator Server Guide for MVS, VSE, and VM (SH23-0256-00) 2 

The following information is also available for VisualAge Generator: 

• VisualAge Generator External Source Format Reference (SH23-0265-01) 

• Migrating Cross System Product Applications to VisualAge Generator 
(SH23-0244-01) 

• VisualAge Generator Templates V4.5 Standard Functions — User's Guide 
(SH23-0269-01) 2 ' 3 
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Part 1. Developing systems with VisualAge Generator 
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Chapter 1 . VisualAge Generator overview 



VisualAge Generator Developer includes a fully integrated development 
environment (IDE) that enables you to script VisualAge Generator parts, 
develop user interfaces (text-based, graphical, and Web-based), test and debug 
applications systems, and generate those systems into applications for various 
run- time environments. 

The IDEs provide library management support as well as full support for 
development in one of two languages: Java or Smalltalk. You can write scripts 
in either of these languages and access those scripts from your VisualAge 
Generator logic parts. VisualAge Generator Developer also provides you with 
a Script Wizard to make developing code in these languages easier. In 
addition, the IDEs provide you with visual GUI client development support. 

Typically, users install either VisualAge for Java or VisualAge Smalltalk and 
then install VisualAge Generator Developer. Each IDE includes a component 
or object based library system. Because all VisualAge Generator parts are 
managed in one of these repositories, this book discusses general library 
management first. For more detailed information on working in VisualAge for 
Java, see "Chapter 2. Managing VAGen parts in VisualAge for Java" on 
page 25. For more detailed information on working in VisualAge Smalltalk, 
see "Chapter 8. Managing VAGen parts in VisualAge Smalltalk" on page 177. 

Documentation for both of the IDEs and VisualAge Generator Developer is 
available from the Help menu of the VisualAge for Java Workbench and the 
VisualAge Smalltalk Organizer. 



Integrated development environments overview 

The following section provides you with an overview of the two integrated 
development environments, in which you create new VAGen parts, manage 
those parts, write scripts and build graphical user interfaces. Components 
covered include: 

• VisualAge for Java Workbench 

• VisualAge Smalltalk Organizer 

• VAGen Parts Browser 

• VisualAge Smalltalk Composition Editor 

• VisualAge for Java Composition Editor 

• VAGen Script Wizard 



© Copyright IBM Corp. 2000 



3 



VisualAge for Java Repository management 

VisualAge Generator code is managed by the same built-in library system 
used by VisualAge for Java. This system facilitates team development and 
code reuse by operating in concert with object-oriented principles and 
providing programmers with an integrated environment in which they can 
develop, share, and manage source code. Code is managed as methods, 
classes and interfaces, projects, and packages. Workspaces enable developers 
to customize their environments. Changes to parts in the repository are 
managed as editions and versions. 

VisualAge for Java repository management 

In this team-development environment, VisualAge Generator and VisualAge 
for Java source code is managed at four levels: 

Methods 

are pieces of executable code that implement the logic of a particular 
behavior for a class. Methods are the smallest unit of source code that 
the repository maintains. Each time a method is changed and saved, 
an edition of its source code is saved in the repository so that 
individual changes can be tracked and managed as classes are 
developed. 

Classes and Interfaces 

are specifications that determine the attributes and behavior of 
software objects. Classes typically contain several attributes and 
methods. Interfaces specify a set of behaviors that unrelated objects 
can use to interact with each other without either object having to 
know the full specification of the other. Both classes and interfaces are 
tracked in the repository. Developers can share versions of classes and 
interfaces and use them as templates to standardize objects across 
code repositories. All VisualAge for Java beans are stored as classes or 
interfaces. 

Packages 

are functionally related sets of classes and interfaces that provide 
developers with reusable pieces of functionality. Developers can also 
create and share versions of packages. Loaded packages are listed 
under the Packages tab in the Workbench. They are also listed under 
their individual projects under the Projects tab. 

Projects 

are named groups of packages that are usually associated with a 
product or a major component of a product. Projects provide an easy 
way for developers to import and export sets of packages and share 
them with other development teams. The hierarchical relationship 
between projects, packages, and classes and interfaces is shown under 
the Projects tab in the Workbench. 
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Figure 1. VisualAge for Java Workbench 

For more information on VisualAge for Java repository management, refer to 
the online help. 

VisualAge Generator on Java repository management 

The VisualAge Generator team-development environment uses the same 
repository management system as VisualAge for Java, but VisualAge 
Generator adds some enhancements to the environment so there are a few- 
terms that apply to VisualAge Generator development only: 

VAGen parts 

are units of VisualAge Generator 4GL code that are associated with a 
Java method in a VAGen part class. VAGen parts are listed in the 
VisualAge Generator Parts Browser and are displayed in the VAGen 
Parts pane depending on your selections in the Types pane. To display 
the VAGen Parts Browser, select the Workspace menu, then VAGen 
Parts Browser. You can open a VAGen part by double-clicking on its 
name in the Parts Browser. 
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VAGen part classes 

are Java classes that are used as templates for creating parts to 
standardize object specifications, attributes, and behavior for different 
part types. VAGen part class names begin with "VAGen." 
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Figure 2. VisualAge for Java Workbench: VAGen Part Classes and Parts 

Version control 

Unlike traditional source code management systems, where source files are 
checked out and checked in, VisualAge for Java's access control authorizes 
groups of developers to work on specific classes, packages, and projects. 
Developers customize their environment by adding to their workspace copies 
of packages (editions) that contain the classes they need to work on. During 
the development cycle, programmers create open editions and scratch editions 
of packages to make changes to code and run tests. But each package and 
each class has a single owner, or manager, who is responsible for releasing 
stable versions at appropriate times. 

Familiarity with the following terms is essential to understanding how to 
manage your code repository: 

Workspace 

In the simplest terms, a workspace is a customized view of items in 
the repository, limited to the packages that contain the parts you need 
to change or test. All developers have a file stored on their 
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workstations that defines their workspace. The default image file 
name is ide.icx. When you save your workspace, this file is updated 
to track which editions and versions of projects and packages you 
have added. The next time you start VisualAge Generator, all the 
projects and packages displayed in your workspace when you saved 
it last will be listed on the Projects and Packages tab of the 
Workbench. 

Edition 

In general, editions are packages that are subject to change. The two 
kinds of editions you will encounter most often are: 

• Open editions — packages that have not been frozen. You can save 
classes to open editions in your workspace, and you can recognize 
them by the date and time stamp enclosed in parentheses next to 
their names in the Workbench. Open package editions can have 
new classes added to them, classes deleted from them, and different 
versions of existing classes released into them. 

Note: Select the Show Edition Names button on the toolbar to 
include edition information beside package and project 
names. 

• Scratch editions — copies of packages that are created automatically 
when you save changes to an edition that is not open. Scratch 
editions allow you to make changes for testing existing classes in 
packages owned by other developers, but you cannot add new 
classes to a scratch edition. Unlike open editions, scratch editions 
are displayed in the Workbench with a version number in single 
angle brackets (<>) beside the edition name. Changes made to 
scratch editions only exist in the image of the developer who made 
them and they cannot be released into a package that does not have 
an open edition. 

Version 

Versions are editions that have been frozen by the application 
manager to prevent further changes to that level of code. They have 
version numbers (without angle brackets) instead of date and time 
stamps next to their names in the Packages pane of the VisualAge for 
Java Workbench. 

For hands-on practice loading packages, creating new editions, and other 
library management tasks, refer to the tutorial in the VisualAge Generator 
Getting Started. 

VisualAge Smalltalk Repository management 

VisualAge Generator code is managed by the same built-in library system 
used by VisualAge Smalltalk. This system, called ENVY, facilitates 
team-development and code reuse by operating in concert with 
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object-oriented principles and providing programmers with an integrated 
environment (Figure 3 on page 9) in which they can develop, share, and 
manage source code. Code is managed as methods (or parts), classes, 
applications, and configuration maps. Images enable developers to customize 
their environments and changes to parts in the repository are managed as 
application editions and versions. 

Managing VisualAge Smalltalk parts 

In this team-development environment VisualAge Generator and VisualAge 
Smalltalk source code is managed at four levels: 

Methods 

are pieces of executable code that implement the logic of a particular 
message for a class. Methods are the smallest unit of source code that 
the repository maintains. Each time a method is changed and saved, 
an edition of its source code is saved in the repository, so that 
individual changes can be tracked and managed as classes are 
developed. 

Classes 

are specifications that determine the attributes and behavior of 
software objects. Classes, which typically contain several methods, are 
also tracked in the repository. Developers can share versions of classes 
and use them as templates to standardize objects across code libraries. 
All VisualAge parts are stored as classes. 

ENVY applications 

are functionally related sets of defined and extended classes that 
provide developers with reusable pieces of functionality. Developers 
can also create and share versions of applications. Loaded applications 
are listed in the Applications pane of the VisualAge Organizer 
window. 

Configuration maps 

are named groups of application editions that are usually associated 
with a product or a major component of a product. Configuration 
maps provide an easy way for developers to import and export sets of 
applications and share them with other development teams. 
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Figure 3. VisualAge Organizer window 

For more information on VisualAge for Smalltalk repository management, 
refer to the IBM Smalltalk User's Guide. 



VisualAge Generator on Smalltalk repository management 

The VisualAge Generator team-development environment (Figure 4 on 
page 10) uses the same library management system as VisualAge Smalltalk, 
but VisualAge Generator adds some enhancements to the environment, so 
there are a few terms that apply to VisualAge Generator development only: 

VAGen parts 

are units of VisualAge Generator 4GL code that are associated with a 
Smalltalk method in an extension of a VAGen part class. VAGen parts 
are listed by part type in the VAGen parts pane (available only if you 
have installed VisualAge Generator) in the VisualAge Organizer 
window. You can also look at an alphabetical list of VAGen parts 
associated with a loaded application by opening the VAGen Parts 
Browser. You can open a VAGen part by double-clicking on its name 
in either window. 

VAGen part classes 

are extensions of a VisualAge part class. Like VisualAge part classes, 
they are used as templates for creating parts to standardize object 
specifications, attributes, and behavior for different part types. VAGen 
part classes listed in the Parts pane in the VisualAge Organizer 
window have as the first five letters of their class names "VAGen." 
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Figure 4. VisualAge Organizer Window: VAGen Part Classes and Parts. 

Version control 

Unlike traditional source code management systems, where source files are 
checked out and checked in, VisualAge's access control authorizes groups of 
developers to work on specific part classes, applications, and configuration 
maps. Developers customize their workspaces by loading copies of the 
applications (editions) containing the parts they need to work on into their 
image. During the development cycle, programmers create open editions and 
scratch editions of applications to make changes to code and run tests. But 
each application, and each part class has a single owner, or manager, who is 
responsible for releasing stable versions at appropriate times. 



Familiarity with the following terms is essential to understanding how to use 
ENVY to manage your code libraries: 

Image In the simplest terms, an image is a customized view of items in the 
repository, limited to the applications that contain the parts you need 
to change or test. All developers have an image file stored on their 
workstations. The default image file name is abt.icx. When you save 
your image, this file is updated to track which editions and versions 
of applications you have loaded. The next time you start VisualAge 



10 VisualAge Generator: User's Guide 



Generator, all the applications that were loaded into your image when 
you saved it last will be listed in the VisualAge Organizer window 
and in the VAGen Parts Browser. 

Edition 

In general, editions are applications that are subject to change. The 
two kinds of editions you will encounter most often are: 

• Open editions — applications that have not been frozen. You can 
save parts to loaded open editions, and you can recognize them by 
the date and time stamp next to their names in the Applications 
pane of the VisualAge Organizer window. Open application 
editions can have new classes added to them, classes deleted from 
them, and different versions of existing classes released into them. 

• Scratch editions — copies of applications that are created 
automatically when you save changes to an edition that is not open. 
Scratch editions allow you to make changes for testing existing 
classes in applications owned by other developers, but you cannot 
add new classes to a scratch edition. Unlike open editions, scratch 
editions have a version number in double angle brackets («») 
instead of a date and time stamp beside the application name in the 
Applications pane of the VisualAge Organizer window. Changes 
made to scratch editions only exist in the image of the developer 
who made them and they cannot be released into an application 
that does not have an open edition. 

Version 

Versions are editions that have been frozen by the application 
manager to prevent further changes to that level of code. They have 
version numbers (without angle brackets) instead of date and time 
stamps next to their names in the Applications pane of the VisualAge 
Organizer window. 

For hands-on practice loading applications, creating new editions, and other 
repository management tasks, refer to the tutorial in the VisualAge Generator 
Getting Started. 



VisualAge Generator Developer 

VisualAge Generator Developer provides you with editors in which you can 
create and edit logic, data, and text-based user interfaces. For a brief 
description of the kinds of parts you can build with VisualAge Generator 
Developer, see "Part types" on page 12. One of the easiest ways to work with 
VAGen parts is using the VAGen Parts Browser. For a brief description of this 
browser, see "VAGen Parts Browser" on page 16. For details on how to use the 
VAGen Parts Browser on VisualAge for Java, see "Using the VAGen Parts 
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Browser" on page 43. For details on how to use the VAGen Parts Browser on 
VisualAge Smalltalk, see "Using the VAGen Parts Browser" on page 195. 

Note: The VAGen Parts Browser is available in both IDEs, but the 

terminology is different depending on which IDE you are using it in. 
So, in the following paragraphs, for example, you will see the library 
part containers referred to as packages / applications. Packages are part 
containers in VisualAge for Java and applications are part containers in 
VisualAge Smalltalk. 

Part types 

Parts used with VisualAge Generator are described in the following table. 



Part Type 


Part Class 


Part Description 


Program 


VAGenPrograms 


A program is a set of related parts that 
VisualAge Generator can generate into 
executable form. 


Function 
□ 


VAGenFunctions 


A function is a block of logic consisting of a 
set of statements. Functions can be used as 
subroutines or to perform input or output 
(I/O) operations. Processing operations or I/O 
options are provided as high-level verbs. Some 
examples are: 

• Converse - display a screen and wait for 
input 

• Add - add information to a file or database 

• Scan - read information from a file or 
database 


Map 

s 


VAGenMaps 


A map defines the layout and characteristics 
for all or part of the information presented on 
a character-based screen or printout when 
users run associated programs. 


Map Group 
if 1 


VAGenMapGroups 


Each map is part of a named collection called 
a map group. All maps used in an application 
must be in the same map group, except for 
help maps, which can be in a separate map 
group. 


Record 

a 


VAGenRecords 


A record is a collection of data items (a data 
structure) organized to serve a specific 
purpose. Records are analogous to rows in a 
database table. Records can be used to describe 
the layout of information in memory, in a 
database table, or in a file. 
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Part Type 


Part Class 


Part Description 


Table 
# 


VAGenTables 


A table is a collection of related data items that 
can be used to edit data, store messages that a 
program issues, and store information for 
reference by an application system. 


PSB 


VAGenPSBs 


A program specification block (PSB) describes 
the hierarchical database structures that an 
application system uses to access DL/I 
databases. 


Data Item 
i 


VAGenDataltems 


A data item describes the characteristics of a 
single unit of information in a record or table. 


Generation 
Options 

-> 


VAGenOptions 


Generation options are parts managed in the 
library that list specifications used to 
customize generation for different 
environments. 


Linkage 
Table 

0* 


VAGenLinkages 


A linkage table lists specifications required for 
calls to non-VisualAge Generator programs or 
calls to VisualAge Generator servers on remote 
systems. 


Resource 
Associations 


VAGenRe sources 


Resource associations specify default overrides 
used during generation of COBOL or 
CICS/6000 programs that use printer maps or 
serial, indexed, or relative files. 


Dina 
Controls 


VAGenBindControls 


Bind controls list commands that control DB2 
applications. They are used in the COBOL 
program generation process. 


Link Edit 

0 


VAGenLinkEdits 


Link edits contain program-specific control 
statements used in generation of programs that 
run in MVS, VSE, and VM environments and 
call or are called by other programs using 
static COBOL calls. 
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Figure 5. VAGen Parts Browser 

The VAGen Parts Browser provides you with a complete listing of all of the 
VAGen parts loaded in your workspace/image. You can also control how the 
list is displayed. Using the Parts Browser, you can display VAGen parts by 
package/ application or part type. You can also sort them by name. 



If you are using VisualAge Generator Developer on Java, you can open the 
VAGen Parts Browser from the Workbench by selecting Workspace-»Open 
VAGen Parts Browser. 



If you are using VisualAge Generator Developer on Smalltalk, you can open 
the VAGen Parts Browser from the VisualAge Organizer window by selecting 
VAGen Parts+Parts Browser. 



To begin building new VAGen parts, you'll use the New VAGen Part window, 
shown in Figure 6 on page 15. 

In this window, you'll name your new part, choose the part type, and select a 
package/ application to contain it. 

If you are using VisualAge Generator Developer on Java, you can display the 
New VAGen Part window from the VAGen Parts Browser by selecting VAGen 
Parts-* Add-»New Part. 
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If you are using VisualAge Generator Developer on Smalltalk, you can display 
the New VAGen Part window from the VAGen Parts Browser by selecting 
VAGen Parts->New. 



lew VAGen Pari 



Part name: 



(sample) 



Part type — 
HJ (* Program 
I I C Function 
C' MapG/oup 
r Map 




Figure 6. New VAGen Part 

For hands-on practice developing VAGen parts, complete the steps outlined in 
VisualAge Generator Getting Started. 
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Figure 7. VAGen Parts Browser 

The VAGen Parts Browser provides you with a complete listing of all of the 
VAGen parts loaded in your workspace/image. You can also control how the 
list is displayed. Using the Parts Browser, you can display VAGen parts by 
package/ application or part type. You can also sort them by name. 

If you are using VisualAge Generator Developer on Java, you can open the 
VAGen Parts Browser from the Workbench by selecting Workspace-»Open 
VAGen Parts Browser. 



If you are using VisualAge Generator Developer on Smalltalk, you can open 
the VAGen Parts Browser from the VisualAge Organizer window by selecting 
VAGen Parts-»Parts Browser. 



VAGen clients 

Included with each of the IDEs is a visual composition editor that you can use 
to build graphical user interfaces or GUI clients. In this editor you select parts 
from the palette and drop them on the free-form surface. Then you visually 
connect those parts using different events, properties, actions, or attributes, 
depending on how you want the GUI client to function. 

For details on how to use the Composition Editor in VisualAge for Java, see 
"Chapter 7. Developing GUIs with VisualAge for Java" on page 147. For 
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details on how to use the Composition Editor in VisualAge Smalltalk, see 
"Chapter 13. Developing GUIs with VisualAge Smalltalk" on page 295. 

Note: The Composition Editor is available in both IDEs, but the terminology 
is different depending on which IDE you are using it in. So, in the 
following paragraphs, for example, you will see the library part 
containers referred to as packages / applications. Packages are part 
containers in VisualAge for Java and applications are part containers in 
VisualAge Smalltalk. 

VisualAge Composition Editor 

The VisualAge Composition Editor, shown in Figure 8, is used to build 
VisualAge visual and nonvisual parts. A visual part has a visual 
representation at run time. It can include other visual parts, such as windows, 
labels, text parts (text entry fields), and push buttons. 
It can also include nonvisual parts — parts that don't have visual 
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Figure 8. Composition Editor on Smalltalk 

representations at run time. A set of VAGen nonvisual parts are available to 
be used with the Composition Editor. As you build your user interface, the 
Composition Editor enables you to visually define connections that control 
how that interface communicates with other parts. 
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Figure 9. Composition Editor on Java 

The Composition Editor provides you with the following: 
Tool bar 

The horizontal row of icons that appear underneath the menu bar. The 
tool bar provides convenient access to common functions, such as 
aligning and sizing your visual parts. 

Beans/Parts palette 

The two vertical columns of icons that appear on the left side of the 
screen contain the parts you use to construct your graphical user 
interface. The left column is the set of part categories, and the right 
column is the set of parts within the selected part category. 
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Status area 

The scrollable static text field at the bottom of the screen. This field 
displays information about your last definition operation or your 
current selection. 

Free-form surface 

The large open area in the middle of the screen where you place parts 
to visually define a GUI. 

You can specify the user interface characteristics and logic flow visually by 
doing the following: 

• Selecting visual parts from the Beans /Parts palette and placing them on the 
free-form surface. Visual parts, such as push buttons, entry fields, and 
windows, are the basic components of user interfaces. 

• Defining connections between visual parts and Visual Age Generator parts. 
For example, the GET-NEXT VAGen function is connected to the Find 
button. When users click the Find button, the GET-NEXT function will be 
performed. 

• Specifying settings options to further refine the appearance and function of 
the part. 

• Building VisualAge Generator parts, such as records and tables, to be used 
as your data structures and functions and programs to be used as the 
procedural logic for your application systems. 

Refer to the online help for VisualAge for Java or the VisualAge for Smalltalk 
User's Guide for more information on designing visual parts. 

For hands-on practice building visual parts, complete the steps outlined in 
VisualAge Generator Getting Started, or in VisualAge Generator Getting Started.. 

VAGen Script Wizard 

The VAGen Script Wizard (shown in Figure 10 on page 21) is an extension 
provided by VisualAge Generator to augment the capabilities of the 
Composition Editor. It enables you to quickly and easily compose simple 
scripts that get or set property values, or invoke methods in your parts. These 
scripts use the syntax of an object-oriented language (shipped as part of your 
development environment) without requiring you to master a new 
programming language. These scripts can be invoked from VAGen functions 
and give you access to non- VisualAge Generator parts, like graphical user 
interface objects or Enterprise JavaBeans (EJBs), during execution of your 4GL 
logic. Using the wizard can help reduce the number of static connections you 
make between objects on the free-form surface. It simplifies maintenance and 
can improve the performance of your visually composed clients. 

Before you compose a script, lay out your parts visually and save the part or 
bean. To display the wizard, if you are using VisualAge Generator on Java, 
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select the Members tab, followed by the Members menu, and then VAGen 
Script Wizard. If you are using VisualAge Generator on Smalltalk, select the 
Script Editor icon, followed by the VAGen Script Wizard icon. 

Methods developed with the VAGen Script Wizard are called VAGen scripts 
or object scripts and are associated with the instance of the class (the GUI 
client) in which you develop them. You can access these scripts by including 
the reserved word EZESCRPT in a VAGen function and specifying the literal 
script name or a data item that contains the script name. Scripts invoked this 
way cannot require arguments. EZESCRPT cannot be used to pass arguments 
to your scripts, but you can share information between your GUI client and 
your 4GL parts by storing data in a record placed on the free-form surface of 
the GUI client where you are developing the script. 

The VAGen Script Wizard steps you through the process of naming a script, 
declaring local variables, choosing patterns (including get 

properties / attributes, set properties / attributes, invoke method / send message, 
and perform action), and selecting objects to get data from and pass data to. 
For example, if a condition specified in your VAGen function is not met by 
input received from a GUI client, you can indicate which field is in error by 
using a VAGen Script to change the color of that field. 
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VAGen Script Wizard - TutorialView 

Enter a script name and an optional comment and select Next. 



The script you are creating is a method that accepts no arguments. You can access this script from a 

VAGen Function using the following syntax: 

EZESCRPTCrnvSctipf). 



Script name: 
Comment 



Composed script: 



public void (] { 
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} catch (java.lang.Throwable iv|Exc) { 
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Figure 10. VAGen Script Wizard 



Areas: The VAGen Script Wizard has five areas on each window that provide 
you with information or allow you to enter data and make selections: 

Action text 

The action text is displayed at the top of each panel and directs you to 
make a selection or type text for the current step. 

Assist mode text 

The Assist mode text provides you with additional information about 
what to do in each step and, where appropriate, gives examples. 
When you start the VAGen Script Wizard, the Assist mode text is 
displayed. You can turn it off and on by selecting the Assist Mode 
button. 

Work area 

The work area displays a set of fields where you specify logic and 
data to be used in your script. Depending on the step you are 
working on, different fields are displayed and the fields change as 
you develop your script. See the section on the panel you are working 
with for more specific information about this area. 
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Script area 

The script area displays the current state of your script. This area is 
for display only but if you know the syntax for the statement you 
want to add, you can select Free-form statement from the work area 
and type statements directly into an edit window. 

You can also use the Back button to sequentially remove changes that 
you added, change a step, and then use the Next button to add your 
selections back in. 

Status area 

The status area located near the bottom of the window provides you 
with valuable information about your selections as you make them. 
For example, if the Next button is still not available after you make a 
selection, the status bar prompts you for another action. 
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Part 2. Using VisualAge Generator Developer on Java 
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All activity in VisualAge for Java is organized around a single workspace, 
which contains the source code for the programs that you are currently 
working on. The workspace also contains all the packages, classes, and 
interfaces that are found in the standard Java class libraries and other class 
libraries that you may need. 

All code that you write and save in the workspace is also stored in a 
repository. Code generated by VisualAge for Java and VisualAge Generator is 
automatically stored in the repository. In addition, the repository contains 
other packages that you can add to the workspace if you need to use them. 

In VisualAge for Java, you can manage the changes that you make to a 
program element by creating editions of the program element. The workspace 
contains at most one edition of any program element. The repository, on the 
other hand, contains all editions of all program elements. 

VisualAge Generator stores VAGen parts in Java packages. Before you build a 
new VAGen part, you must create a new package or load an edition of a 
package to contain the parts you create. 

When you start VisualAge Generator, two windows will be displayed on your 
desktop: the Log window and the Workbench window. 



Creating a project 

A project is the topmost program element in the IDE hierarchy of program 
elements. A project contains all the packages used for a particular work unit, 
such as an entire application. 

To create a new project: 

1 . Select the New Project button in the Workbench. The Add Project 
SmartGuide is displayed. (This SmartGuide is also used for adding 
projects from the repository to the workspace). 

2. Select Create a new project named. 

3. Type a name for the project. 

4. Select Finish. 

The new project will appear in the Projects page of the Workbench. To add a 
descriptive comment for the new project, select it, and fill in a description in 
the Comment pane of the Projects page. 
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Creating a package 

A package is Java language construct that groups classes. You can add a 
package to any project in the workspace. 

To create a new package: 

1 . Select the New Package button in the Workbench. The Add Package 
SmartGuide is displayed. (This SmartGuide is also used for adding 
packages from the repository to the workspace). 

2. Follow the SmartGuide instructions to create the new package. 

The new package will appear in the Projects and Packages pages of the 
Workbench. To add a descriptive comment for the new package, select it, and 
fill in a description in the Comment pane. 

Once you have created a package you can add classes and interfaces to it. 

In the team development environment, only the project owner can add a 
package to a project. 



Creating a class 

The Add Class SmartGuide makes creating classes an easy-to-follow process. 
To create a new class: 

1 . Before you launch the SmartGuide, select the package you want the class 
to belong to, and if applicable, the class within that package that the new 
class will extend. This will set some defaults within the SmartGuide to 
make your work easier. 

2. To launch the SmartGuide, select the New Class button on the toolbar of 
the Workbench or a browser. Follow the SmartGuide instructions to add 
the new class to the workspace. 

In the team development environment, you must be a member of the package 
group in order to add a class to an existing package. If you are creating the 
package at the same time as the class, then you must own the project that 
contains the package. 



Importing and loading projects and packages 

To import and load a project or package: 

1 . From the Workbench, select the File menu, then Import. 

2. Select Repository. 

3. Using the Import from another repository SmartGuide, specify the 
location of the repository (.DAT file). 
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4. To import projects, select the Projects radio button, then select Details and 
select the projects you want to load. 

Note: You can also import individual packages by selecting the Packages 
radio button, the Details button and then the packages you want to 
import. 

5. Select Finish to finish importing. 

6. To load imported projects into your workspace, from the Projects tab 
Selected menu, select Add-* Project. 

Note: You can load packages using these same instructions if you 

selectAdd+Package. If you want to add packages instead of projects, 
you must have an open edition of a project in your workspace to 
add packages to. 

7. Select Add projects from the repository and select the project to load. 

8. Select the appropriate edition. 

9. When you have finished selecting all the projects you want to load, select 
Finish. 



Versioning and releasing 

When you version a program element, you prevent further changes to the 
parts and classes it contains. Version names are usually followed by a version 
number. Unversioned class names are preceded by a right angle bracket (>) 
and followed by a date and time stamp. Unversioned packages /applications 
names are preceded by an open folder icon and followed by a date and time 
stamp. 

To version a class: 

1 . From the Workbench, in the Types pane, select an open edition of a class 
of which you are the owner. 

2. From the Types menu, select Manage-* Version. 

To release a class: 

1 . From the Workbench Types pane, select a versioned edition of a class. 

2. From the Types menu, select Release. 

To version a package: 

1 . From the Workbench Packages pane, select an open edition. 

2. From the Packages menu, select Version. 
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Working with VAGen parts 

A part consists of both a name and a complete definition. 

You can define and work with the following types of parts in VisualAge 
Generator: 

• Program 

• Function 

• Map Group 

• Map 

• Record 

• Table 

• PSB 

• Data Item 

• Generation Options 

• Linkage Table 

• Resource Associations 

• Bind Control 

• Link Edit 

You can work with parts in the following ways. 

Importing VAGen parts 

If you want to work with VisualAge Generator parts that are in an external 
source format, you can import them into VisualAge Generator Developer. You 
can import VAGen parts from an external source format file on the 
workstation. 

To import an external source format file, complete the following tasks: 

1 . From the VAGen Parts Browser, from the VAGen Parts menu, select 
Import/Export* VAGen Import. 

2. On the Select a file to import window, specify the full path name for the 
external source format file you want to import. Then select OK. 

After you select a file to import, the VAGen Import window is opened. 

Exporting VAGen parts 

After you define and test a program and its associated parts, you can export a 
single part, all first found parts, or all the parts within a single program. You 
can export the parts and place them in an external source format file, which 
can then be imported by other developers who prepare and generate the parts 
for the run-time environment. They can prepare a single part or all the parts 
within a single program. 

You can export VAGen parts to an external source format file on the 
workstation. 
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Alternatively, you can create a batch command to export the external source 
format of your parts. 

Manipulating VAGen parts 

VAGen parts include programs, functions, map groups, maps, records, tables, 
program specification blocks (PSBs), data items, generation options parts, 
linkage tables, resource associations parts, bind control parts, and link edit 
parts. You define each of these types of parts using the Visual Age Generator 
Developer editors. 

From the VAGen Parts Browser, you can select the packages and types of 
parts you want displayed in the browser. To change the parts listed in the 
browser, from the Part names field, specify the criteria to sort the list of parts 
in the browser. 

Creating a new VAGen part 

To create a new VAGen part: 

1 . From the Workbench, select the Workspace menu then Open VAGen Parts 
Browser 

2. From the VAGen Parts Browser, select the VAGen Parts menu ■» Add ■* 
New Part. 

3. In the New Part field, enter a valid part name. 

4. Select a part type. 

5. Select a valid package to add your VAGen part to. 

6. Select OK. 

Package 

Use the Package drop-down list to select the package to contain the newly 
defined parts. 

The drop-down list will contain only valid target packages for VAGen part 
types. 

Valid target packages must already contain the VAGen Part class of the 
selected type. 

If the target package does not contain the VAGen Part class, the package must 
meet the following preconditions: 

• The target package must be an open edition, and you must be a group 
member. 

Note: A scratch edition is not an open edition. You can add VAGen parts to 
package scratch editions, but only if the package already contains an 
extension of the VAGen Part class for the type of part you want to add. 
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Creating a new program 

To create a new program: 

1 . On the VAGen Parts Browser, select the VAGen Parts menu, then Add. 
or 

From the Program Editor, select the File menu, then New. 

2. In the New Part field, enter a valid program name. 

3. Select Program as the part type. 

4. Select a valid package to add your program to. 

5. Select OK. The new part is displayed in the Program Editor. 

6. In the Program Editor, select the type for the program from the Program 
Type/Execution Mode drop-down list box on the tool bar. 

Program names 

Use the following conventions when naming programs: 

• Maximum length: 7 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

• DBCS name: No 

• Set testpoints: Yes 

• The program name must be unique within a CICS execution system and 
within a target MVS load library 

• To avoid potential conflicts with the program names generated for the map 
groups, do not end the program name with FM or PI 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

• Part names cannot be COBOL reserved words. 

Package 

Use the Package drop-down list to select the package to contain the newly 
defined parts. 

The drop-down list will contain only valid target packages for VAGen part 
types. 

Valid target packages must already contain the VAGen Part class of the 
selected type. 

If the target package does not contain the VAGen Part class, the package must 
meet the following preconditions: 

• The target package must be an open edition, and you must be a group 
member. 
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Note: A scratch edition is not an open edition. You can add VAGen parts to 
package scratch editions, but only if the package already contains an 
extension of the VAGen Part class for the type of part you want to add. 

Setting program options 

To set program options: 

1 . On the VAGen Parts Browser, select the Window menu, then Options. 

2. Select the Program page to set the available options. 

Creating a new function 

A function is a block of logic consisting of a set of statements surrounding a 
central operation. 

To create a new function: 

1 . From the VAGen Parts Browser, select the VAGen Parts menu, then New. 
or 

From the Function Editor, select the File menu, then New. 

2. In the New Part field, enter a valid function name. 

3. Select Function as the part type. 

4. Select a valid package to add your function to. 

5. Select OK. 

Function names 

Use the following conventions when naming functions: 

• Maximum length: 18 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9), underscore (_), hyphen ( — ), or 
one of the valid national characters for your workstation 

• DBCS name: Yes, maximum length: 8 

• Set testpoints: Yes 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

To avoid aliases being assigned during COBOL generation, and to improve 
the readability of the generated COBOL program, use a name that meets the 
following COBOL naming conventions: 

• Do not use COBOL reserved words. 

• Do not use @, #, $, or _ characters. 

• Do not use DBCS names. 
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For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 

Defining a map group 

When you create a new map, you specify the name of its map group. An icon 
for the map group you choose is displayed in the Specifications section of the 
program diagram. If you want to see a list of maps in a map group that are 
using a particular device, you must first define the map group. To define a 
map group: 

1 . Open a program that uses a map from the map group you want to define. 

2. In the Program Editor, double-click on the Map Group part under 
Specifications. 

3. In the New Part package window, ensure that the part name and part type 
are correct, then select the name of the package you want to add the map 
group to. 

4. Select OK. 

Creating a new map 

1 . On the VAGen Parts Browser, select the VAGen Parts menu ■* Add ■» New 
Part. 

or 

In the Map Editor, select the File menu, then New. 

2. In the New Part field, enter a map group name and a map name 
separated by a space. The name you enter first is the map group name. 
The name you enter second is the map name. 

3. Select Map as the part type. 

4. Select a valid package to add your map to. 

5. Select OK. The new part is displayed in the Map Editor. 

Map group names 

Use the following conventions when naming map groups: 

• Maximum length: 6 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

• DBCS name: No 

• Set testpoints: No 

• The map group name cannot have the same name as the map 

• The map group name cannot have the same name as another program in 
the MVS library or the same CICS system 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 
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• Part names cannot contain embedded blanks. 

Note: The following compatibility considerations exist for the naming of 
maps and map groups: 

IMS/VS All maps in a map group are generated in a single MFS 

message input description (MID) or message output 
description (MOD) per device. If you have a large map 
group, it can exceed the 32K size limit for MFS control 
blocks. For more information on estimating the size, 
refer to the Design Guide document. 

IMS BMP If you specify the MSP(MFS) or the MSP(ALL) 
generation option, the IMS/VS compatibility 
considerations apply. Otherwise, there are no 
compatibility considerations. 

Map names 

When you name a map, you must precede the map name with a map group 
name followed by a space. 

Use the following conventions when naming maps: 

• Maximum length: 8 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9), or one of the valid national 
characters for your workstation 

• DBCS name: No 

• Set testpoints: Yes 

• The map name cannot have the same name as the map group 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

Note: The naming conventions for variable field names are the same as for 
data item names. 

Map group names: Use the following conventions when naming map 
groups: 

• Maximum length: 6 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

• DBCS name: No 



Chapter 2. Managing VAGen parts in VisualAge for Java 33 



• Set testpoints: No 

• The map group name cannot have the same name as the map 

• The map group name cannot have the same name as another program in 
the MVS library or the same CICS system 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

Note: The following compatibility considerations exist for the naming of 
maps and map groups: 

IMS/VS All maps in a map group are generated in a single MFS 

message input description (MID) or message output 
description (MOD) per device. If you have a large map 
group, it can exceed the 32K size limit for MFS control 
blocks. For more information on estimating the size, 
refer to the Desigti Guide document. 

IMS BMP If you specify the MSP(MFS) or the MSP(ALL) 
generation option, the IMS/VS compatibility 
considerations apply. Otherwise, there are no 
compatibility considerations. 

Data item names: Use the following conventions when naming data items: 

• Maximum length: 32 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9), underscore (_), hyphen (-), or 
one of the valid national characters for your workstation 

• DBCS name: Yes, Maximum length: 15 

• Set testpoints: No 

• An asterisk can be used as the data item name in any record or table 
structure. This type of data item is called a filler data item, which cannot be 
referenced by a program. The name acts as a place holder in a data 
structure 

• A data item name can be used only once within a single record or table 

• To avoid aliases being assigned during COBOL generation and to improve 
the readability of the generated COBOL program, use a name that meets 
the following COBOL naming conventions: 

- Use 30 characters or less in data item names. 

- Do not use DBCS names for data item names if your program contains 
SQL functions. 

- Do not use COBOL reserved words. 
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- Do not use @, #, $, or _ characters. 

For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

Data items in DL/I records name 

Data item names used in DL/I records are limited to 8 characters. They 
cannot be DBCS names or contain hyphens or underscores. If you want to use 
long names for data items in a DL/I record, define a redefined record for the 
DL/I segment and use long names for the fields in the redefined record. Use 
the DL/I segment definition only as the I/O object and in defining DL/I calls. 

For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 

Package 

Use the Package drop-down list to select the package to contain the newly 
defined parts. 

The drop-down list will contain only valid target packages for VAGen part 
types. 

Valid target packages must already contain the VAGen Part class of the 
selected type. 

If the target package does not contain the VAGen Part class, the package must 
meet the following preconditions: 

• The target package must be an open edition, and you must be a group 
member. 

Note: A scratch edition is not an open edition. You can add VAGen parts to 
package scratch editions, but only if the package already contains an 
extension of the VAGen Part class for the type of part you want to add. 

Setting map options 

To set map options, on the VAGen Parts Browser, select the Window menu, 
then Options. Select Map to set the available options. 

Creating a new record 

A record is a collection of related data items treated as one unit. Records in 
VisualAge Generator are the information units that form a file or database. 
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To create a new record: 

1 . From the Workbench, select the Workspace menu then Open VAGen Parts 
Browser 

2. From the VAGen Parts Browser, select the VAGen Parts menu then Add. 
or 

From the Record Editor, select the File menu, then New. 

3. In the New Part field, enter a valid part name. 

4. Select Record as the part type. 

5. Select a valid package to add your record to. 

6. Select OK. 

7. In the Record Editor, select the type for the record from the Record Type 
drop-down list box on the tool bar. 

8. Select a usage from the Default Usage list box. 

Record names 

Use the following conventions when naming records: 

• Maximum length: 18 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9), underscore (_), hyphen ( — ), or 
one of the valid national characters for your workstation 

• DBCS name: Yes, maximum length: 8 

• Set testpoints: Yes 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

To avoid aliases being assigned during COBOL generation, and to improve 
the readability of the generated COBOL program, use a name that meets the 
following COBOL naming conventions: 

• Do not use COBOL reserved words. 

• Do not use @, #, $, or _ characters. 

• Do not use DBCS names. 

DL/I records name 

DL/I record names are limited to 8 characters. They cannot be DBCS names, 
nor can they contain hyphens or underscores. If you want to use long names 
for a DL/I record, define a redefined record for the DL/I record using long 
names in the redefined record. You can use the redefined record name 
everywhere in the program except as an I/O object name. 

SQL row records 
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You cannot use filler data items in a SQL row record. Any data item named 
with an asterisk (*) is a filler item. 

For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 

Package 

Use the Package drop-down list to select the package to contain the newly 
defined parts. 

The drop-down list will contain only valid target packages for VAGen part 
types. 

Valid target packages must already contain the VAGen Part class of the 
selected type. 

If the target package does not contain the VAGen Part class, the package must 
meet the following preconditions: 

• The target package must be an open edition, and you must be a group 
member. 

Note: A scratch edition is not an open edition. You can add VAGen parts to 
package scratch editions, but only if the package already contains an 
extension of the VAGen Part class for the type of part you want to add. 

Creating a new table 

A table is a collection of related data items used in editing data entered by 
your user on a user interface such as a map or HTML page or in storing 
information for reference by a program when it runs. 

To create a new table: 

1 . From the Workbench, select the Workspace menu then Open VAGen Parts 
Browser 

2. From the VAGen Parts Browser, select the VAGen Parts menu then Add. 
or 

From the Table Editor, select the File menu, then New. 

3. In the New Part field, enter a valid table name. 

4. Select Table as the part type. 

5. Select a valid package to add your table to. 

6. Select OK. 

7. In the Table Editor, select the type for the table from the Table Type 
drop-down list box on the tool bar. 

Table names 

Use the following conventions when naming tables: 

• Maximum length: 7 
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• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

• DBCS name: No. 

• Set testpoints: Yes 

• Table names cannot end with a 0 (zero) 

• The table name must be unique within a CICS execution system and within 
a target MVS load library 

• To avoid potential conflicts with the program names generated for the map 
groups, do not end the table name with FM or PI 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

See the rules for the prefix for message tables. 

Message table prefixes: Use the following conventions when naming 
message table prefixes: 

• Maximum length: 4 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

The message table prefix is specified in the Properties window in the Program 
Editor. 

A suffix is appended to the message table prefix to build the name of the user 
message table. The suffixes for the national languages supported by VisualAge 



Generator are: 


Code 


Language 


CHS 


Simplified Chinese 


CHT 


Traditional Chinese 


DES 


Swiss German 


DEU 


German 


ENP 


Uppercase English 


ENU 


US English 


ESP 


Spanish 


FRA 


French 


ITA 


Italian 


JPN 


Japanese 


KOR 


Korean 


PTB 


Brazilian Portuguese 
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Note: Uppercase English is not supported by AIX, OS/2, Windows NT, 
HP-UX, SCO OpenServer, and Solaris. 

Creating a new PSB 

To create a new PSB: 

1 . From the VAGen Parts menu, select Add 
or 

From the PSB Editor, select the File menu, then New. 

2. In the New Part field, enter a valid PSB name. 

3. Select PSB as the part type. 

4. Select a valid package for your function. 

5. Select OK. 

PSB names 

Use the following conventions when naming PSBs: 

• Maximum length: 8 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9) or one of the valid national 
characters for your workstation 

• DBCS name: No 

• Set testpoints: No 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

To avoid aliases being assigned during COBOL generation, and to improve 
the readability of the generated COBOL program, use a name that meets the 
following COBOL naming conventions: 

• Do not use COBOL reserved words. 

• Do not use @, #, $, or _ characters. 

For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 

Package 

Use the Package drop-down list to select the package to contain the newly 
defined parts. 

The drop-down list will contain only valid target packages for VAGen part 
types. 
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Valid target packages must already contain the VAGen Part class of the 
selected type. 

If the target package does not contain the VAGen Part class, the package must 
meet the following preconditions: 

• The target package must be an open edition, and you must be a group 
member. 

Note: A scratch edition is not an open edition. You can add VAGen parts to 
package scratch editions, but only if the package already contains an 
extension of the VAGen Part class for the type of part you want to add. 

Defining a shared data item 

You can define shared data items using the Data Item Editor. 

Steps for defining a shared data item 

1 . To open a data item, do one of the following: 

• From the Workbench, select the Workspace menu then Open VAGen 
Parts Browser 

• From the VAGen Parts Browser, select the VAGen Parts menu then 
Open to open an existing shared data item. 

or 

From the Data Item Editor, select the File menu, then Open to open an 
existing shared data item in the Data Item Editor. 

• From the Workbench, select the Workspace menu then Open VAGen 
Parts Browser 

• From the VAGen Parts Browser, select the VAGen Parts menu then Add 
to create a shared data item. On the New VAGen Part window, select 
the Data Item button, enter a name for the data item, and select a 
package to attach your new data item to. When you select Save from 
the File menu, the Data Item Editor is opened. 

or 

From the Data Item Editor, select the File menu, then New to define a 
shared data item in the Data Item Editor. 

• From the Workbench, select the Workspace menu then Open VAGen 
Parts Browser 

• From the VAGen Parts Browser, select the VAGen Parts menu then 
Open to open an existing shared data item. 

or 

From the Data Item Editor, select the File menu, then Open to open an 
existing shared data item in the Data Item Editor. 

• From the VAGen Part or the File menu, select New to define a new 
shared data item. 
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2. In the Data Item Editor, you can specify the following types of 
information: 

• The data type 

• The length of the data item, either when displayed or when stored 
internally 

• If it is a numeric data item, the number of decimal places 

• A description of the data item 

3. To define default map edit characteristics for a shared data item in the 
Data Item Editor, from the Define menu, select Default Map Properties. 

4. To define UI properties for a shared data item in the Data Item Editor, 
from the Define menu, select UI Properties. 

5. After you finish defining or editing the shared data item, select Save from 
the File menu in the Data Item Editor to save the changes. Then close the 
Data Item Editor. 

For an existing shared data item, you can create a copy of the shared data 
item with a new name. From the File menu, select Save as. 

Setting generation options from the UI 

You can set generation options from the user interface (UI). Each target 
environment has a set of generation options available from the generation 
options notebooks. You are not required to specify values for the generation 
options because default values are provided. 

When NOOVERRIDE is specified for an option in the generation options 
defaults file, the field corresponding to that option is not available and the 
value defined in the default file is displayed. For details, refer to "Establishing 
default generation options" in the VisualAge Generator Generation Guide. 

Setting generation options 

For VisualAge Generator Developer on Java, there are two kinds of 
"generation options" you can set. You can specify default preferences for 
generation on the VisualAge Generator Options page and you can also set 
specific generation options on the Generate window or by creating a 
Generation Options part. 

To set default generation preferences: 

1 . From the Workbench, select Workspace^Open VAGen Parts Browser. 

2. From the VAGen Parts Browser, select Window ^Options 

3. On the VisualAge Generator Options navigation pane, select Generation. 

4. For code generated for the client, in the Client group box, select a 
generation options part. 

5. For code generated for the server, in the Server group box, select a 
generation options part. 
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6. You can generate server programs in batch by specifying commands in a 
generation options file. When you use the generation UI for batch 
generation, a command file is created for you that contains one of the 
following commands: 

HPTCMD Select this command if you are generating on the local 
machine. 

CALL EFKREQ 

Select this command if you are generating on a remote 
(Generation Server) machine. 

User specified Select this command if you want to specify the name of 
the program that will control generation of the selected 
parts. The program you specify must use HPTCMD or 
CALL EFKREQ commands directly or indirectly. 

Creating a linkage table 

For information on creating a linkage table, refer to the appendix on linkage 
tables in the VisualAge Generator Client/Server Communications Guide. 

Creating a resource associations part 

To create a resource associations part, take the following steps: 

1 . Create a new VAGen part. 

2. For the part type, select Others and then Resource Associations. 

3. Enter the name of your resource associations part and select OK. 

When you generate a COBOL or CICS/6000 application that uses serial, 
relative, or indexed files, or printer maps, you can use a resource associations 
part to associate target-system dependent file characteristics, including the file 
type and the system file or resource name, with the file name specified in the 
VAGen record definition. 

Refer to the VisualAge Generator Generation Gwzdedocument for information 
about resource association. 

Creating a bind control part 

For information on creating a bind control part, refer to the chapter on bind 
control parts in the VisualAge Generator Generation Guide. 

Creating a link edit part 

For information on creating a link edit part, refer to the chapter on link edit 
parts in the VisualAge Generator Generation Guide. 
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Chapter 3. Developing VAGen parts 



You can start building VAGen parts from the Compostion Editor or from the 
VAGen Parts Browser. For more information about building GUI clients, see 
"Chapter 7. Developing GUIs with VisualAge for Java" on page 147. 



Using the VAGen Parts Browser 

After you have created or imported projects and packages to store your 
VAGen parts, use the VAGen Parts Browser to create new parts and customize 
your view of VAGen parts loaded into your workspace. 

To open the VAGen Parts Browser, from the VisualAge for Java Workbench, 
select Workspace+Open VAGen Parts Browser. 

To create a new part from the VAGen Parts Browser, select VAGen 
Parts-»Add-»New Part. For more information about creating new parts, see 
"Working with VAGen parts" on page 28. 

Reordering columns 

To reorder columns in the VAGen parts list: 

1 . From the VAGen Parts Browser, from the VAGen Parts menu, select View, 
then Reorder Columns. 

2. In the Reorder Columns window, drag and drop column heading names 
where you want them. The heading name at the top of the list is the first 
column displayed in the VAGen parts list. Other heading names above the 
Hidden Columns line are displayed consecutively from left to right. You 
can also drag the Hidden Columns line to a new location. 

3. Select Apply, to accept and view your changes or OK to accept your 
changes and close the Reorder Columns window. 

Hiding columns 

For faster display time in the VAGen Parts Browser, consider hiding columns 
you don't need to see. Hiding Description, or Part Type and Subtype can 
noticeably improve performance. 

Customizing the status bar 

To change the information displayed in the status bar area: 

1 . From the VAGen Parts Browser, from the VAGen Parts menu, select View, 
then Reorder Status Bar Text. 

2. In the Reorder Status Bar Text window, drag and drop column heading 
names where you want them. The first heading name in the list is the first 
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piece of information displayed in the status bar. Information under other 
heading names above the Hidden Columns line is displayed consecutively 
from right to left. 

To hide the status bar, drag the Hidden Columns line to the top of the list. 
3. Select Apply, to accept and view your changes or OK to accept your 
changes and close the Reorder Status Bar Text window. 

Sorting information 

There are two ways to sort information displayed in the VAGen Parts 
Browser. 

• In the VAGen parts list, click on a column heading to sort the parts by that 
column. For example, if you click on the Part Name column heading, the 
parts will be reordered alphabetically by part name. 

• To sort using menus: 

1 . From the VAGen Parts menu, select View-»Sort by. 

2. From any of the Sort by menu items select a type of sort. 

Note: Using this method, you can sort on columns that are not 

displayed in the VAGen parts list, but you might find it more 
helpful to display the column you are sorting on. 

Note: Selecting the same sort order again (or clicking on the column twice) 

reverses the sort order. For instance, if you select Sort by Name, the list 
is displayed in alphabetically ascending order (a-z). If you select it 
again, the list will be sorted in alphabetically descending order (z-a). 

Filtering information 

To filter the parts displayed in the VAGen Parts pane, select items from the 
Packages / Applications and Types panes or type a pattern in the Part Names 
filter. Only parts matching the filter criteria are displayed. 

If you use the Show Names Filter from the References window, select items 
from the Packages / Applications or Types panes or type a pattern in the Part 
Names filter to change the scope of your search for part references. When 
changes to the filter are made, the references search is performed again. 

Saving your settings as defaults 

To save your VAGen Parts Browser settings as defaults, from the Window 
menu, select Save Settings as Defaults to save the window size, sort order, 
columns shown, column sizes, and status bar text displayed in the VAGen 
Parts Browser. 

The saved values will be used when opening a new VAGen Parts Browser. 
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Enabling the V3 to V4 migration tool 

You can enable the migration tool using the command line or the product 
icon. 

You can start VisualAge Generator 4.5 with the migration tools by selecting 
the icon in the VisualAge Generator 4.5 program folder for VAGen on Java 
with Migration. 

To start VisualAge Generator 4.5 with the migration tools from a command 
prompt, use these steps: 

1 . Open a command line window to the directory where the ide.icx file is 
stored, and enter the command 
ide /vgmig 



2. From the VisualAge for Java Workspace window, select Workspace-»Open 
VAGen Parts Browser. The VAGen Parts Browser window is displayed. 

3. From the VAGen Parts Browser window, select Tools-»Migration-»V3 to V4 
Migration. The main Migrator window, called V3 to V4 Migration, is 
displayed. 



Programs 

A VAGen program contains elements that define the structure of the program. 
Functions and flow statement definitions implement business logic through 
statements that handle data when the program runs. 

Think of a VisualAge Generator program as a collection of modular pieces, 
defined primarily by the different types of input and output (I/O) required. 
Each I/O operation requires a separate logic block, and additional supporting 
business logic can be included in that block. 

Program logic: 

• Displays panels and prints reports 

• Accesses files and databases 

• Moves data among records, maps, files and databases 

• Performs arithmetic calculations and other types of operations 

I/O options and I/O objects are accessed by functions to perform these tasks. 

A sequence of main functions defines the default flow of the main program 
logic. To modify the default flow of the logic, you can define flow statements 
for each of the main functions. Flow statements are stored with the program; 
they are not part of the function. 
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Defining a program 

When you define a program, you are actually defining functions, maps, 
records, and other types of parts. Depending on the type of program you are 
building, you might not need to do all of the following tasks. If you are 
creating a new program, the following steps are arranged in logical order. 

To define a program: 

1 . Create a new program 

2. Define the Program Type/Execution Mode. 

3. Define program properties 

4. Define program specifications 

5. Define additional records and tables 

6. Define called parameters 

7. Define program logic 

8. Define a program prolog 

Selecting a program type 

To select a program type: 

1 . In the Program Editor, select one of the Program Type / Execution Mode 

menu choices: 

Main Transaction - Nonsegmented 

Choose the Main Transaction - Nonsegmented Program Type / Execution 
Mode when you want I/O locks and database and file positions maintained 
across a CONVERSE. When you select Main transaction - Nonsegmented, a 
CONVERSE does not mark the end of a unit of work. 

You should choose a Main Transaction type when you want to start the 
program by a transfer from the system or another program and you want 
your user to interact with the program using maps. 

Main Transaction - Segmented 

Choose the Main Transaction - Segmented Program Type / Execution Mode 
when you want each write to the terminal (CONVERSE or XFER with map) to 
be the end of a unit of work. 

You should choose a Main Transaction type when you want to start the 
program by a transfer from the system or another program and you want 
your user to interact with the program using maps. 

Main Transaction - Single Segment 

Choose the Main Transaction - Single Segment Program Type / Execution 
Mode when you want to stop the program after processing a single input 
from the terminal or when control transfers to another program. When you 
select Main Transaction - Single Segment, you must use the XFER statement 
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with a map and a first map for all terminal I/O operations. The CONVERSE 
I/O option is not allowed in Main Transaction - Single Segment programs. 

You should choose a Main Transaction type when you want to start the 
program by a transfer from the system or another program and you want 
your user to interact with the program using maps. 

Web Transaction 

Choose the Web Transaction Program Type / Execution Mode when you want 
to start the program by a transfer from the system or another program and 
you want your user to interact with the program through a Web browser 
using HTML pages and forms. You should choose Web Transaction when you 
want to develop a Web application. 

The VisualAge Generator Web Transaction programming model enables you 
to develop 4GL-based business systems that use a Web browser to display the 
user interface and generated run-time programs for business logic and 
database processing. The Web Transaction programming model is related to 
the model used for Text User Interface (TUI) programming in VisualAge 
Generator. Similar component roles exist, and the method of interacting with 
your user is based on a similar use of either the 4GL CONVERSE processing 
option or XFER single segment transfer technique. Using a Web Transaction 
program, you can define a web application as a single threaded program 
which interacts with your user by sending business data directly to a browser 
through the use of the User Interface Record data definition and either the 
CONVERSE or XFER language verb. 

The execution mode of a Web Transaction program is like a Main transaction - 
Segmented program in that each write to the back end system or web server 
is the end of a unit of work. Unlike Main Transactions, where the generated 
user interface closely resembles the user interface you see in the VisualAge 
Generator Map editor, the outputs from generating a Web Transaction 
program include a Java bean with user interface data. The generated UI 
record bean contains data definitions, edits, and default HTML. User interface 
developers can customize the HTML page presented to your user through a 
Web browser by modifying or adding new information to the contents of the 
generated UI record bean. 

The process of developing and implementing a Web application using the 
Web Transaction programming model includes creating Web Transaction 
programs and UI records, and using such elements generated by or provided 
with VisualAge Generator as UI record beans, resource bundles, JSPs, the 
GatewayServlet and Session ID Manager. For information on developing and 
implementing Web Transaction programs, see Building e-Business Transaction 
Systems with VisualAge Generator: Using the Web-Transaction Programming Model 
(SG24-5636-00). 
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Called Transaction 

Choose the Called Transaction Program Type / Execution Mode when you 
want to call the program from another program and you want your user to 
interact with the program using maps. When you select Called transaction, 
the called program can pass and reset parameters. 

Main Batch 

Choose the Main Batch Program Type / Execution Mode when you want to 
start the program by a transfer from the system or another program and you 
do not want your user to interact with the program using maps. 

Called Batch 

Choose the Called Batch Program Type / Execution Mode when you want to 
call the program from another program and you do not want your user to 
interact with the program using maps. When you select Called Batch, the 
called program can pass and reset parameters. You should choose Called 
Batch for server programs called from remote clients and for subroutine 
programs that do not converse or display 3270 maps. 

Defining program properties 

To define program properties: 

1 . In the Program Editor, select the Define menu, then Properties. 

2. On the Program Properties window, enter appropriate values for your 
program and select OK. 

Defining specifications 

To define specifications for your program: 

1 . In the Program Editor, click mouse button 2 on the Specifications symbol 
in the diagram and select the type of part you want to add: Working 
Storage, PSB, Firstmap, Map Group, or Help Map Group. 

2. Type a valid part name in the Part name field and select OK. 

3. In the Program Editor, double-click on the new part, to display it in the 
appropriate editor. 

4. Make any changes you need to and save the part. 

You can also replace, delete, or edit parts in this section by clicking on them 
with mouse button 2 and selecting the appropriate choice from the context 
menu. 

Defining tables and additional records 

In the Specifications section of the program diagram, you can define Tables 
and Additional Records. 

An additional record is: 

• A record that is not the working storage record defined in the Program 
Editor. 
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• A record that does not appear in the called parameter list 

• A record that is not displayed as an I/O object for a function in the 
program 

Before you start defining additional tables /records, expand the Tables and 
Additional Records section to see a list of parts that are already defined. 

To expand the list, click on the gray square to the left of the Tables and 
Additional Records symbol. 

To add an additional record or table: 

1 . Click mouse button 2 on the Tables and Additional Records symbol and 
select Insert Table/Record from the context menu. 

2. On the Insert Table/Record window, select a part type and a part name. 

3. Select OK. 

4. If you selected a part that is not already defined in the library, double-click 
on it in the Program Editor to finish defining it. 

You can also replace, delete, or edit parts in this section by clicking on them 
with mouse button 2 and selecting the appropriate choice from the context 
menu. 

Note: Tables that are referenced in program logic or used as map edit 
routines must be specified in the Tables and Additional Records. 

Defining called parameters 

In the Specifications section of the program diagram, you can define Called 
Parameters for Called Transactions or Called Batches. The Called Parameters 
symbol is only displayed in the Specifications section for programs of these 
two types. To define a called parameter: 

1 . Click mouse button 2 on the Called Parameters symbol and select Insert 
Parameter from the context menu. 

2. On the Insert Parameter window, select a part type and a part name. 

3. Select OK. 

4. If you selected a part that is not already defined in the library, double-click 
on it in the Program Editor to finish defining it. 

You can also replace, delete, or edit parts in this section by clicking on them 
with mouse button 2 and selecting the appropriate choice from the context 
menu. 

Defining program logic 

To define program logic: 
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1 . Add a main function to the program, by clicking mouse button 2 on the 
Structure Diagram symbol and selecting Insert Main Function. 

2. On the Insert Main Function window, specify a name for the function; 
then select OK. 

3. To further define the main function, double-click on the main function 
symbol. 

4. On the New Part Package/ Application window, select a 
package/application to contain the function and select OK to display the 
Function Editor. 

5. In the Function Editor, use Statement Templates to define logic 
statements. 

6. (Optional) To define flow statements for the program, in the Program 
Editor, click mouse button 2 on a main function. From the context menu 
select Flow Statements. 

Note: Flow statements are associated with the main function, but stored 
with the program. 

Defining a program prolog 

Describe and comment your program in a prolog. To add a prolog to your 
program: 

1 . In the white space outside the program diagram in Program Editor, click 
with mouse button 2 and select Prolog from the context menu. 

or 

In the Program Editor, select the Define menu, then Prolog. 

2. In the Prolog window, type your description. To use editing functions in 
the Prolog window, click with mouse button 2 in the white space and 
select a function from the context menu. 

3. Select OK to save your description and close the window. 
Working with program diagrams 

Collapsing/Expanding symbols 

Symbols with a + (collapsed) or - (expanded) to the left of the symbol have a 
subtree of symbols that can be hidden or shown as desired by clicking on the 
+ or -. The subtree for a symbol will be expanded one level by clicking on the 
+. Use the context menu to expand the whole subtree with a single action. 

You can set your Program preferences to control the initial display of the 
structure diagram section of the program diagram. The default is to initially 
show only the main functions. 

Note: It is recommended, especially for large program diagrams, to leave the 
initial display set for main functions, and then expand symbols only as 
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you need to work with that portion of the logic. Only the parts 
required to display the symbols are read from the library so additional 
reading of parts is delayed until you start expanding symbols. 
However, once you expand a symbol, you cannot buy back the memory 
required for the subtree by collapsing the symbol. 

Editing parts 

You can open the editor for any VisualAge Generator part displayed on the 
program diagram by double-clicking the symbol for the part. "Edit part" is 
available from the context menu for a symbol and does the same thing as the 
double-click. If the part has not yet been defined, the New Part 
Package / Application window is displayed, which enables you to create the 
part and then open the editor. 

Managing lists 

The "Tables and Additional Records", "Called Parameters", and "Structure 
Diagram" symbols represent a list of parts, which are shown as the children of 
the Descriptor symbol. You can insert, delete, and move these parts within 
each list. 

All "Insert" actions will add the new part AFTER the symbol for which you 
perform the "Insert" action. To insert a new part as the first part in the list, 
invoke the context menu on the Descriptor symbol. Thus, if you want to insert 
a new main function as the first function to be executed, invoke the context 
menu on the "Structure Diagram" symbol and select "Insert Main Function". 

You can reorder the parts in the list by dragging and dropping one or more 
parts to a new position in the list. As with "Insert" actions, you should drop 
the dragged symbols onto the symbol AFTER which you want the dropped 
symbols to be placed. 

Editing tasks 

While editing text, you can perform the following tasks: 
Insert a line 

Move the cursor to the end of the line and press Enter. 
Split a line 

Move the cursor to the position where you want to split the line and 
press Enter. 

Join two lines 

Move the cursor to the end of the first line to be joined and press 
Delete. 

Select text 

Move the cursor to the beginning of the text you want to select. Press 
and hold mouse button 1. Drag the mouse to the end of the text you 
want to select. Release mouse button 1. 
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Note: When text is selected, pressing any character key replaces the 
selected text with the new character. 



Functions 

A function is built around a specific operation called an I/O option. An I/O 
option is the I/O operation the function performs, such as displaying a map 
or gaining access to a record. 

The map or record you specify as the object of the I/O operation is called the 
I/O object. You can specify only one I/O object for each function. 

Add statements before or after the I/O object and I/O option to complete 
your function. One of the easiest ways to add statements is using the 
Statements Templates editor.For specific instructions, see the section on using 
the Statement Templates editor. 

For more information on transferring control between programs, see 
"Appendix E. Program Control Linkage Conventions" on page 407. 

Defining I/O options and I/O objects 

1 . In the Function Editor select an I/O Option from the first drop-down list 
to the right of the tool bar icons. 

2. (Optional) If you need to use an I/O Object, select one from the second 
drop-down list to the right of the tool bar icons. 

Note: The I/O object list is not available for EXECUTE I/O options. 

• If you select an SQL row record as a I/O object, from the Define menu, 
select SQL statement to define the SQL statements for this function. If 
you have not already set your SQL preferences, ensure that the default 
settings are acceptable. 

• If you want to use a segment in a DL/I database as a I/O object, you 
must first define the segment as a PCB in a PSB. Then, from the 
Function Editor you can select Define then DL/I Call to specify the 
DL/I call as a function object. If you have not already set your DL/I 
preferences, ensure that the default settings are acceptable. 

Defining function properties 

To define function properties: 

1 . From the Define menu, select Properties. 

2. If you specified a record as an I/O option, type the name of a part or 
select a part from the Error routine list box to specify an Error routine. 

3. In the Description field, type a 1-30 character description of the function. 

4. (Optional) You can select the Default collapse check box to set the default 
display of the function, as it appears in the Program Editor, to collapsed. 
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This means that any parts under the function in the program hierarchy are 
hidden, unless you expand the Structure Diagram. 

5. Select OK. 
Error routine 

If you want the function you are working with to have an error routine, select 
an error routine from the drop-down list or type the 1- to 18-character name 
of the error routine in the Error routine field. 

If you specify a function, the function name cannot be the same as the 
function being edited. 

If you do not specify an error routine, a program ends when an error occurs 
with a message describing the error condition. This includes standard 
situations such as the end-of-file (EOF) condition. 

You cannot specify error routines for functions with map I/O objects or for 
EXECUTE functions. Display or printer errors cause the program to end. 

The error routine can be any of the following: 

• A valid special function word EZERTN, EZEFLO, or EZECLOS. 

• The name of a function 

The function must be defined as a main function in the same program as 
the function used as an error routine. 

If the error routine is a function, then control is transferred to that function 
when an error occurs. Control returns to the statement following the I/O 
option after the error routine ends. 

You can test error codes returned by the system using the TEST, WHILE, and 
IF statements. 

Defining logic 

To define logic for your part, do any of the following: 

• Type statements directly into the statements area in the editor. You can use 
the standard editing tasks to update the statements. 

• Use the Statement Templates window to add statements. To use the 
Statement Templates window: 

- From the Tools menu, select Statement Templates. 

- To view lists of statements, EZE words, or service routines that you can 
paste into the statements area, select the type of statement you want to 
work with from the Categories list box. 

• To verify that the statements you added are valid, from the Tools menu, 
select Validate or Validate and Format. 
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If an error is identified during validation, the Validation Errors window is 
displayed. Correct any errors displayed in this window before you save or 
the part or close the editor. 

For more information on specific language elements, refer to the online help 

or the VisualAge Generator Programmer's Reference. 

For more information on transferring control between programs, see 
"Appendix E. Program Control Linkage Conventions" on page 407. 



Editing tasks 

While editing text, you can perform the following tasks: 
Insert a line 

Move the cursor to the end of the line and press Enter. 
Split a line 

Move the cursor to the position where you want to split the line and 
press Enter. 

Join two lines 

Move the cursor to the end of the first line to be joined and press 
Delete. 

Select text 

Move the cursor to the beginning of the text you want to select. Press 
and hold mouse button 1. Drag the mouse to the end of the text you 
want to select. Release mouse button 1. 

Note: When text is selected, pressing any character key replaces the 
selected text with the new character. 



Records 

A record or multiple records are individually accessible units of storage in a 
file or database. Records can also be used as temporary working storage when 
a program runs. A record consists of: 
• A specific record organization 

The record organization indicates both the structure of the file or database 
containing the collection of records and how to gain access to the record. 
You can choose from the following types of organizations: 

- DL/I segment 

- Indexed 

- Redefined 

- Relative 

- Serial 

- SQL row 
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- User Interface 

- Working storage 
• A list of data items 

Defining a record 

If you are defining a new record, the following tasks are arranged in logical 
order 

1 . Create a new record 

2. Make a selection from the Record Type list box. 

3. Make a selection from the Default Usage list box. 

4. Define record properties 

5. Define record prolog 

Define record properties 

From the Define menu in the Record Editor, select Properties to define or 
change record properties. Working storage records do not have properties. 
Additional information is available for each properties window when you 
select the window by name in the navigation frame of the online help. 

If you are working with a UI record, additional properties may be defined on 
the Record Data Item UI Properties window. To access the Record Data Item 
UI Properties window: 

1 . In the UI Properties column, select the UI Properties field for the data item 
you want to define. 

2. Select the pushbutton that appears beside the field. 

You can select Record Data Item UI Properties in the navigation frame of the 
online help for more information. 

Define record prolog 

To provide a record description, select Prolog from the Define menu in the 
Record Editor. 

Working with substructured data items 

In the editor, you can move data items between structures and alter the 
parent / child relationship of substructured data items by selecting a data item 
and dragging it to a new position in the list of data items. 

To move a substructured data item between structures and maintain the item 
at the same level, select the item and drag it to a new position in the list. You 
can move only one item at a time. However, if you select an item with 
children, the children are moved with the data item. You cannot move an item 
within its own structure. 
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To move a substructured data item between structures and change the item's 
level, select the item, press the Alt key, and drag the item to a new position in 
the list. This enables you to move the data item to another structure as a child 
in the structure. 

Editing records 

To edit an existing record, do one of the following: 

• From the File menu within the Record Editor, select Open. 

• From the Parts Browser, select Open from the VAGen Parts menu. 

To select an individual data item, click on the item with mouse button 1. 

To select multiple data items in a record, click on the first data item with 
mouse button 1, then press and hold the Shift key and click on the last data 
item with mouse button 1. 

You can add and modify data items in the Record Editor. Select a data item 
using the mouse and press the mouse button 2 to display the context menu of 
available actions for the selected data item. The context menu varies 
depending on the record type, number of data items selected and data item 

type- 
Some data item manipulation can be performed from choices in the Edit 
menu, but all available data item actions are provided by the context menu. 
Use the context menu to create Level 77 data items and add substructured 
data items. 

To validate and correct structural errors in the record, select Validate Data 
Structure from the Tools menu. Validation finds: 

• Data items whose types or lengths need to be changed based on the 
Substructure or Occurs values for those data items 

• Duplicate data item names 

When you close the Record Editor, you will be prompted to save your 
changes. If you defined new shared data items, you will be prompted to 
create and save these data items. 

Inserting, moving, and deleting data items 

You can insert a data item into the list by selecting an item in the list and 
choosing Insert before or Insert after from the Edit menu. You can also 
choose Insert Parent or Insert Substructure if your record is not an SQL Row 
record. 

Note: If you select Insert After and have not selected an entry in the list, the 
item is inserted at the end of the list. If you select Insert Before and 
have not selected an entry in the list, the item is inserted at the 
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beginning of the list. If you do not have an entry in the list, you can 
still select Insert Before or Insert After from the Edit menu. 

You can Copy and Paste an item from another record or table to insert a data 
item. 

You can move a data item by selecting it and dragging it to a new position in 
the list. You can also use Cut and Paste to move a data item. 

To delete a data item, select the item and choose Delete from the Edit menu. 

Working with shared data item definitions 

You can view and update a shared data item by selecting the data item, 
pressing mouse button 2, and selecting Edit part from the context menu. If the 
selected data item is nonshared, Edit part is not available. 

Creating a Ul record from a map 

This feature is available from the Organizer (VisualAge Generator on 
Smalltalk only) and the Parts Browser from the VAGen Parts pulldown as 
VAGen Parts ■* Create UI Record from Map. 

To create a corresponding working storage record, change the record type 
from UI to working storage. When you change the record type from UI 
record, all Ul-record-related data is removed. 

Creating core data item information 

For core data item information, local data items are created based on variable 
field data. Table 2 shows the relationship. 



Table 2. How variable map field properties are converted to core data item properties 



Map data 


UI record data 
item 


Comment 


map field 
name 


data item 
name 


Unnamed map field names become filler items 
(name='*') in the UI record with an UI type of NONE. 
Map edits are not converted for unnamed map fields 
because filler items do not have UI properties. Map 
fields named EZEMSG is changed to data items named 
EZMSG. There is at most one EZEMSG variable field 
per record. 


map type 


data item type 


Since there are fewer map types, the resulting data item 
types are limited to Char, DBCS, Mixed and Num. 
Variable fields with Hex edit selected results in a Char 
data item. Hex edit is not supported for UI properties. 


map 

description 


data item 
description 
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Table 2. How variable map field properties are converted to core data item 
properties (continued) 



Map data 


UI record data 
item 


Comment 


map length 


data item 
bytes 


The maximum bytes /length for numeric data items is 
18. If a numeric map field has a length greater than 18, 
the data item bytes/length is set to 18. 


map 
decimals 


data item 
decimals for 
numeric fields 





Creating record data item information 

For record data item information, the data item level defaults to 3. The UI 
type defaults to Input /Output except for filler items and data items named 
EZMSG. Filler items must have a UI type of None with no UI properties. The 
UI type for data items named EZMSG is set to Output. 

For record data item information, local data items are created based on 
variable field data as shown in Table 3. 



Table 3. How variable map field properties are converted to record data item 
properties 



Map data 


UI record data 


Comments 


map field 
array size 


data item 
occurs 


If a map field is not an array, the data item occurs 
defaults to 1. 


map field 
edit order 


data item edit 
order 


Only Input or Input/ Output data items have an edit 
order value. Filler data items and Output data items 
have an input edit order of 0. For maps, all variable 
fields have an edit order assigned to it. 


map field 
name 


data item UI 
label 


The UI label for filler data items is blank. 



Removing EZMSG form the input edit order list may cause the input edit 
order value for other data items to change. Data items with an input edit 
order greater than the edit order of the EZEMSG variable field, from which 
the EZMSG data item was created, will have its input edit order value 
decreased by 1. 
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Creating general Ul edits 

Table 4. How general map edits are converted to general Ul edits 



Map edit 


Data item edit 


Comments 


Check SO/SI space 


Check SO /SI space 


Convert as is. Check SO/SI 
should be set only for mixed 
data items. 


Edit routine 


Edit function 


If the edit routine is actually an 
edit table, it is up to you to 
make this change. 


Fill character 


Fill character 


A fill character of null is not 
supported for Ul properties. A 
null fill character is converted to 
a space. 


Date edit mask 


Date 


If a date edit mask is defined, 
the data item date flag is set. 


Fold 


Fold 


If Variable field folding is 
selected from the Map 
Properties, the data item fold 
flag is set for all Char and Mixed 
Input/ Output data items that are 
created for the Ul record. Fold is 
valid for Char and Mixed data 
items. 


Input required 


Input required 


Convert as is. 


Minimum input 


Minimum input 


Convert as is. 


Edit routine message 
number 


Edit function message 
key 


Convert number to string. A 
message number of 0 results in a 
message key of blank. If the edit 
routine message number is 
actually an edit table message 
key, the user has to make this 
change. 


Minimum input message 
number 


Minimum input 
required message key 


Input required message 
number 


Input required message 
key 


Data type message 
number 


Data type message key 
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Creating numeric Ul edits 

Table 5. How numeric map edits are converted to numeric Ul edits 



Map edit 


Data item edit 


Comments 


Currency 


Currency 


Numeric map edits are converted only 
for numeric map fields. 


Separator 


Separator 


Minimum value 


Minimum value 


Maximum value 


Maximum value 


Sign 


Sign 


Zero edit 


Zero edit 


Numeric range 
message number 


Numeric range 
message key 


Convert number to string. A message 
number of 0 results in a message key of 
blank. Converted only for numeric fields. 



Tables 

A table is a collection of related data items structured as a two-dimensional 
array of rows and columns. The columns of the array are individually 
specified data items. 

You can use a table name as the edit routine that supplies edit characteristics 
for a variable field on a map. The table is then used for checking map field 
input when the program rims. When data entered by the program user fails a 
table edit check, an error message is displayed. You can define the following 
types of tables for map editing: 

• Match valid 

• Match invalid 

• Range match valid 

You can define reference tables that a program uses when it runs. Visual Age 
Generator statements can be used to search and retrieve data from a reference 
table. You can use the same three types of tables as reference tables that you 
used for map editing. In addition, you can use the following types of tables 
exclusively for reference: 

• Unspecified 

• Message 

Defining a table 

If you are creating a new table, the following tasks are arranged in logical 
order. 
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Creating a new message table 

You can create a new message table in the Table Editor. 

To create a new message table: 

1 . Create a two column table. 

2. Define the table type and column types according to your application: 

• For Web Transaction programs: 

- The table type can be Message table type or Unspecified table type 

- Either column can be character or mixed type. 

• For other programs: 

- The table type must be Message table type: 

- Column one must be numeric type. Column two can be either 
character or mixed type. 

3. Fill out the table with message Keys in column one and Messages in 
column two. 

Define table properties 

From the Define menu within the Table Editor, select Properties to define or 
change table properties. 

Define table contents 

To define the table's contents, select Table Contents from the Define menu. 

Inserting, moving, and deleting data items 

You can insert a data item into the list by selecting an item in the list and 
choosing Insert before or Insert after from the Edit menu. You can also 
choose Insert Parent or Insert Substructure if your record is not an SQL Row 

record. 

Note: If you select Insert After and have not selected an entry in the list, the 
item is inserted at the end of the list. If you select Insert Before and 
have not selected an entry in the list, the item is inserted at the 
beginning of the list. If you do not have an entry in the list, you can 
still select Insert Before or Insert After from the Edit menu. 

You can Copy and Paste an item from another record or table to insert a data 
item. 

You can move a data item by selecting it and dragging it to a new position in 
the list. You can also use Cut and Paste to move a data item. 

To delete a data item, select the item and choose Delete from the Edit menu. 

Working with substructured data items 

In the editor, you can move data items between structures and alter the 
parent / child relationship of substructured data items by selecting a data item 
and dragging it to a new position in the list of data items. 
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To move a substructured data item between structures and maintain the item 
at the same level, select the item and drag it to a new position in the list. You 
can move only one item at a time. However, if you select an item with 
children, the children are moved with the data item. You cannot move an item 
within its own structure. 

To move a substructured data item between structures and change the item's 
level, select the item, press the Alt key, and drag the item to a new position in 
the list. This enables you to move the data item to another structure as a child 
in the structure. 

Working with shared data item definitions 

You can view and update a shared data item by selecting the data item, 
pressing mouse button 2, and selecting Edit part from the context menu. If the 
selected data item is nonshared, Edit part is not available. 



PCB restrictions 



Table 6. Restrictions for inserting PCBs into a PSB list 



PCB Type 


Restrictions for PCB types in a PSB 


TP 


Must come before all DB and all GSAM 


DB 


Must come after all TP and before all GSAM 


Segment 


Must come after a DB or between Segments 


GSAM 


Must come after all DB 



PSBs 

A program specification block (PSB) is a formal DL/I description of the 
hierarchical database structures that a program can gain access to. Visual Age 
Generator Developer supports the definition of a part in the library that 
contains a subset of the information in the DL/I PSB. The PSB definition 
describes the hierarchical relationship between types of segments. 

A PSB is made up of program communication blocks (PCBs). You define the 
PSB by defining its PCBs. The types of PCBs are: 

• DB (database) 

• TP (teleprocessing) 

• GSAM 

Each DB PCB describes one database hierarchy. In the IMS environment, PCBs 
also serve to identify IMS message queues or GSAM databases. 
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You can pass individual PCBs on a call. This allows you to define a program 
with a PSB and call the program from other programs that have different PSB 
structures. You use the special function word EZEDLPCB, subscripted with 
the PCB number to be passed, on the CALL statement. 

Defining a program specification block (PSB) 

In the PSB Editor, you can define a set of DL/I database structures that a 
program can access. You can use program specification block (PSB) definitions 
to build and validate DL/I calls for I/O functions that access segments in 
DL/I databases. 

From the PSB Editor, you can create and edit PSBs. 
Editing PSBs 

1 . To open an existing PSB for editing, do one of the following: 

• From the File menu in the PSB Editor, select Open. 

• From the VAGen Parts menu, select 

2. In the PSB Editor, select a PCB or segment in the list. Then select Insert 
Before or Insert After. 

If the PSB contains no PCB entries, select Insert Before or Insert After to 
add a new PCB. 

3. On the Choose Type window, specify the type of PCB, and select OK. 

Note: The PCB Restrictions table describes the restrictions on inserting 
PCBs into a PSB. 

4. Depending on the PCB type you select, you might be prompted to further 
define or update information for the PCB. Enter the appropriate 
information on the prompt window and select OK. 

5. To validate and correct any errors in the structure of the PSB, on the PSB 
Editor, from the Tools menu, select Validate Structure. 

PCB restrictions: 



Table 7. Restrictions for inserting PCBs into a PSB list 



PCB Type 


Restrictions for PCB types in a PSB 


TP 


Must come before all DB and all GSAM 


DB 


Must come after all TP and before all GSAM 


Segment 


Must come after a DB or between Segments 


GSAM 


Must come after all DB 



Data items 

Data items are used in records and tables. Data items can have one of the 
following usages within records and tables: 
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Nonshared data items 

Nonshared data item definitions are stored with the record or table 
with which they are defined. Changes to a nonshared data item have 
no effect on definitions of data items with the same name in other 
records or tables. 

Shared data items 

Shared data items are saved as a separate part. They can be referenced 
by any other part. 

When you are creating a data item that is independent of a record or 
table, it is a shared data item. Changes to shared data items affect all 
the records and tables that include that data item as a shared data 
item. 

Within a Map Editor, the edit characteristics of a shared data item are 
used when: 

• You drag a shared data item from a list of parts into the map 
definition. 

• You name a variable field the same name as a shared data item. 

Note: You can have shared data items created from the variable fields 
you create during map definition when you select Create data 
items from map fields on the VisualAge Preferences window, 
on the VAGen - Map tab. 

The following characteristics are dependent on the structure in which the data 
item is defined: Key item, level, occurs, read-only, scope, SQL column name, 
and SQL data code. 

The following characteristics are independent of the structure: Bytes, decimal 
positions, description, length, name, and type. 



Maps 

A map is a text-based user interface used to display information and receive 
input from users. Some general characteristics of maps are as follows: 

• All information on a map is represented by constant and variable fields. 

• Variable fields appear as outlined boxes. 

• Constant fields appear enclosed in brackets. 

• Brackets for the last constant field on the map wraps around to the top of 
the map if there is no field mark at the beginning position of the map. 

• There is no visual distinction between single byte, DBCS, and mixed fields. 
However, if you click on a field, the status area at the bottom of the map 
provides information about the selected field. 
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• The rectangle on the map presentation area indicates the position of the 
map. The rectangle is positioned based on settings in the Layout tab on the 
Map Properties window. 

• When a map is blank, it is treated as if there is an implicit constant field to 
hold the text on the map. 

If you use an existing data item name when you name a variable field, any 
edit characteristics for the data item are automatically assigned to the map 
field. Changing the edit characteristics for the variable field does not affect the 
edit characteristics of the data item. 

If the name of the variable field is not the name of an existing data item, and 
you select Create data items from map fields (on the Map page of the 
Options /Preferences notebook), a new data item is automatically created 
when you save the map. 

Each map is part of a named collection called a Map Group. Each map within 
a map group must have a unique name. All maps used in a program must be 
in the same map group, except for help maps, which can be in a separate map 
group. 

Defining map properties 

Use map properties to define characteristics applied to the entire map. To 
define map properties: 

1 . In the Map Editor, from the Define menu, select Map Properties. 

2. (Optional) To assign a help map, on the General tab, select the name of 
the help map and specify the key you want to display it. 

3. To define the size and position of the map, select the Layout tab and enter 
the appropriate values. If you want to create a floating map, select the 
Floating map check box. 

4. To define the devices that this map can be presented on, select the Devices 
tab. Select device types from the drop-down list box and use the arrow 
buttons to move devices from Available devices list box to the Supported 
devices list box. 

Defining constant fields 

A map is divided into fields. When you create a new field, beginning and 
ending field marks are automatically entered for you based on the field length 
you specify in properties. To add a constant field to the map: 

1. Select 



(Constant part) from the palette and place it on the map presentation area. 
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2. On the Constant Field Properties window, specify the field attributes and 
select OK. 

Note: After you have created a constant field, you can edit its properties by 
double-clicking on the field to open the Constant Field Properties 
window. 

Defining variable fields 

A map is divided into fields. When you create a new field, beginning and 
ending field marks are automatically entered for you based on the field length 
you specify in properties. To add a variable field to the map: 
1 . Select 



EZl 

(Variable part) from the palette and place it on the map presentation area. 

2. On the Variable Field Properties window, specify the general field 
properties, attributes, edits, and error messages as needed. 

Note: On the Edits tab, you can specify General edits as soon as you have 
named the field on the General tab. The Numeric section of the 
Edits tab is only enabled when you select the Numeric edits check 
box on the General tab. 

3. Select OK. 

Note: After you have created a variable field, you can edit its properties by 
double-clicking on the field to open the Variable Field Properties 
window. 

Map arrays 

A map array is specified by giving the same name to each field in the array 
and by specifying a unique index (or subscript) for each field in the array. The 
array variables can be positioned anywhere on the map and the indices do 
not have to be in the same order as the fields appear on the map. All index 
values between 1 and the number of fields in the array must be used for the 
array to be valid; thus, no gaps in the index values are allowed. Use the 
Resequence Array Indices choice on the context menu to renumber array 
indices. 

All variable fields in a map array must have the same data type, length, and 
share the same map edit specifications. Hardware attributes might be different 
for each variable field in the map array. The hardware attributes can be set 
using the Attributes tab on the Variable Field Properties window or changed 
at run time using the SET statement. 



VisualAge Generator: User's Guide 



nmg map arrays 

Map arrays are groups of variable fields on a map. They are typically used to 
manage the same type of data and therefore have the same field length. 
Variable fields in an array also have the same name. Only the subscript or 
index number makes each field name unique. 

After you create a new map array you can make changes to it by doing the 
following: 

• Editing map arrays 

• Extending map arrays 

• Checking map array indices 

Creating a new map array 

To place an array of variable fields on a map: 

1. Select 



(Array part) from the palette and place it on the map. 

2. On the Variable Field Properties window, do the following: 

a. On the Array tab, specify the number of variable fields in the array 
and how you want to place them. 

b. In the Naming direction box, select the direction to be used first in 
numbering the variable fields. 

c. Select the General tab and type a name in the Name field to name the 
array. 

d. In the Length field, specify the length that will apply to every variable 
field in the array 

e. In the Array index field, specify the value you want to start counting 
from. If you want to start numbering with the first element of the array 
variable, specify 1. 

For example, if the map array has 8 variable fields, your array variable 
is named QED, and you want to number the variable fields starting 
with the ninth element of QED, specify 9 in the Array index field. 

f. (Optional) Use the Attributes, Edits, and Error Message tabs to define 
other characteristics of your array. You can specify these characteristics 
now or you can edit them later. 

3. Select OK to place the map array in the map. 
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Editing map arrays 

All variable fields in an array have the same name and properties specified 
when the array was created. To change the properties of all variable fields in 
an array: 

1 . Double-click on a variable field in an array. 

2. On the Variable Field Properties window, navigate through the tabs and 
make any necessary changes. 

3. Select Apply to Array, to apply your changes to all the variable fields in 
the array. Selecting OK applies your changes only to the variable field you 
have selected. 

Extending map arrays 

To extend an existing array: 

1 . Place the cursor where you want to put the first variable field in the 
extension by holding down the Alt key and clicking with mouse button 1 
outside the bounds of the existing array. 

2. From the Map Editor Define menu, select New, then Array. 

3. On the Array tab, do one of the following: 

• Add one or more columns of variable fields to the existing array by 
specifying a number in the Fields across field. 

The values in the Fields down, Lines between, and Spaces between 
fields should match those values for the existing array. 

• Add one or more rows of variable fields to the existing array by 
specifying a number in the Fields down field. 

The values in the Fields across, Lines between, and Spaces between 
fields should match those values for the existing array. 

4. On the General tab, do the following: 

a. In the Name field, specify the name of the existing array that you are 
extending. 

Note: If you specify a different name, you will create a new array 
instead of extending the existing one. You can always rename 
the entire array after you have added an extension. 

b. Specify a length value for the variable fields you are adding. This 
value should match the lengths of the variable fields in the existing 
array. 

c. In the Array index field, specify the next sequential value from the 
existing array index. 

For example, if you want to extend an existing array that has four 
variable fields and you started indexing with the number one, you 
would enter the number five in the Array index field. 
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5. Use the Attributes, Edits, and Error Message tabs to specify the same 
characteristics for the array extension as were specified for the existing 
array. 

6. Select OK. 

To ensure that the array is extended as you intended, check the array indices. 
If the field edit order number (the first number in the tag) is the same for all 
the variable fields in the array, you have successfully extended the array. 

Checking map array indices 

When you save a map, any invalid arrays are automatically resequenced. To 
check an array to ensure that it is indexed as you intended: 

• From the Map Editor Define menu, select Field Edit Order, then Show 
Tags. 

The first number in the tag is the field edit order number and the second 
number is the array index. If you see gaps in the indices, resequence the 
array. 

• To resequence the array, click with mouse button 1 on one of the fields and 
select Resequence Array Indices from the context menu. Resequencing the 
array renumbers the variable fields in the array and ensures that there are 
no gaps in the array indices. 

Note: Resequence Array Indices is not available when the selected variable 
field is not part of an array. 

Viewing a map 

You can view a map two different ways: as your users will see it or with 
markings that make it easy for you to edit. 

To view the map as it is displayed for your users: 

• From the Map Editor View menu, select Preview. Select Preview again to 
continue editing the map. 

While you are editing the map, you can view it in run-time color mode or 
black and white. To change your view for editing a map: 

• From the View menu, select Runtime color mode. Your view changes from 
the default black and white to run-time color mode. 

• Select Runtime color mode again to go back to defining the map in black 
and white. 

Editing maps 

The following are some methods you can use to edit maps: 

• Inserting and editing text 

• Cutting, copying, and pasting 

• Selecting fields 

• Sizing fields 
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• Dragging fields 

• Deleting fields 

• Inserting constants, variables, and arrays 

• Centering fields 

• Using the Field List 

Note: To type text in the Map Editor, you must be in edit mode. To enter edit 
mode, hold down the Alt key and click with mouse button 1 anywhere 
in the map presentation area. 

Inserting and editing text 

To go into edit mode, hold down the Alt key and click with mouse button 1 
anywhere within the map presentation area or within a field, then start 
typing. 

Once you are in edit mode, you can type text in the existing fields of a map 
or directly on a blank map. You can use the arrow keys and all other key 
strokes and selection behavior you can use in a standard text field. Editing 
applies to the current field only and is limited to working within the current 
field on the current line. That is, no reflowing of text occurs when inserting 
and deleting characters. 

When you enter edit mode, all trailing blanks in the currently edited field or 
line are removed. This means that you will not be able to type in overtype 
mode when you reach the end of text on the field or line. In OS/2, press the 
Insert key to go into overtype mode. Overtype mode is not available in 
Windows. 

Using the arrow keys to move from a field or line automatically takes you out 
of edit mode for that field or line and commits the data you have entered. The 
destination field that the cursor moves to automatically opens in edit mode. If 
the cursor reaches the end of the text on the line, the right arrow key acts as a 
space bar and advances the cursor one position to the right. If the cursor 
reaches a field with a size of zero, the cursor will not be visible but the arrow 
keys will still function correctly. 

You cannot type over the field mark positions. Using the arrow key to move 
left or right into a field mark position automatically moves the cursor past the 
field mark position. 

Use the Tab key to move the cursor to the beginning of the next field or the 
back tab to move the cursor to the beginning of the previous field. 

Use the return key to move the cursor to the beginning of the next line. 
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Use the Ctrl+End keys to move the cursor to the end of the map. Use the 
Ctrl+Home keys to move the cursor to the beginning of the map. 

In edit mode, use the Page Up and Page Down keys to scroll the map up or 
down. Use Ctrl+Page Up and Ctrl+Page Down to scroll the map left and 
right. 

Clicking anywhere within the bounds of a field that is currently being edited 
causes the cursor to move to that position in the field (You do not need to 
hold down the Alt key to do this.) 

To exit edit mode, click outside the bounds of the field being edited. This 
causes the text you entered to be committed. 

Selecting fields 

Select a field by placing the mouse pointer over the field you want to select 
and clicking mouse button 1. Two selection handles appear at the top left and 
bottom right positions of the field. 

To select multiple fields: 

1 . Click mouse button 1 where you want to start your selection. 

2. Using the appropriate selection mode, drag to the point where you want 
to end the selection and release the mouse button. This step selects text in 
the highlighted area. 

3. From the Edit menu, select Selection, then Select Fields, to convert your 
text selection to a field selection. 

You can also select more than one field by holding down the Ctrl key and 
clicking on the fields you want to select. 

Deselect fields by holding down the Ctrl key and clicking on the fields you 
want to deselect. 

Sizing fields 

Select the field you want to size, click on the left or right selection handle (the 
cursor changes to a sizing pointer) while holding down mouse button 1 and 
drag the handles horizontally or vertically. 

Use the Grid to help you size fields appropriately. 

When you size a variable field to size 0, the variable field gets replaced by a 
constant field of size 0, since size 0 variable fields are not allowed. 

Press the Esc key to cancel a field sizing operation. 
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Dragging fields 

Move any field on the map to a different position by clicking on it with 
mouse button 2 and dragging it to the new location. 

When you select a field to drag, the cursor changes to a cross hair and a 
dotted outline beside it. 

To move more than one field: 

1 . Select multiple fields by doing one of the following: 

• Drag the mouse pointer over the fields you want to select and 
selectEdit, then Selection, then Select Fields 

orPress and hold the Ctrl key and click the fields with mouse button 1. 

2. Click on one of the selected fields with mouse button 2 and drag the fields 
to the new location. If you click mouse button 2 on a field that is not part 
of your selection, your multiple-field selection will be ignored and you 
will drag only the field you clicked on with mouse button 2. 

Deleting fields 

To delete fields, do the following: 

• Select the field or fields you want to delete and press the Delete key. 

• Select the field or fields you want to delete and from the Edit pull-down 
menu, select Delete, or select Delete from the context menu. 

Cutting, copying, and pasting 

To cut or copy text: 

1 . Select the text using the appropriate selection mode and drag the mouse 
pointer across the text until it is highlighted. 

2. From the Edit menu, select Cut or Copy. 

To paste text you have cut or copied: 

1 . From the Edit menu, select Paste. 

2. Place the mouse pointer (crosshair) where you want to paste the text and 
click once in the map presentation area. 

To cut or copy fields: 

1 . Using the appropriate selection mode, select the text you want to cut or 
copy. 

2. From the Edit menu, select Selection, then Select Fields, to convert your 
text selection to a field selection. 

3. From the Edit menu, select Cut or Copy. 

To paste fields you have cut or copied: 
1 . From the Edit menu, select Paste. 
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2. Place the mouse pointer (crosshair) where you want to paste the fields and 
click once in the map presentation area. 

Note: If you duplicate any variable field names, you are prompted to 

rename the fields or have new names generated for them when you 
save the map. 

Inserting constants, variables, and arrays 

At the position where you want to insert text, hold down the Alt key and 
click mouse button 1. If there is text following the cursor position where you 
have clicked the mouse button, you might have to select that text and delete it 
first before you start typing. 

From the Define pull-down, select New to insert an array, variable, or 
constant field at the cursor position. The fields on the map are adjusted as 
necessary to preserve the data stream of the map. 

Centering fields 

Select the field or fields you want to center, then from the Tools pull-down 
menu, select Center, or select the Center tool icon from the Tool bar. 

Variable Field Edits 

At run time, when input data that is not valid is detected, the map is shown 
to the user along with an error message describing why the data is not valid. 
The user can enter correct data, or press a bypass PF key or any PA key to 
bypass input editing. 

Variable field edit elements are associated with the field name. All the fields 
in a map array share the same edit specifications. 

On the Variable Field Properties window, select the Edits tab to set variable 
field edit specifications. 

Listing maps by device 

To list maps in a defined map group that use a particular device: 

1 . Open the Map Group from which you want a list of maps. 

2. In the Map Group Editor, select the device you want to display a list for. 

3. From the Options menu, select List of Maps. 

4. Select Close. 

Note: You can only view a list of maps in map groups that have been fully 
defined. 

Creating a Ul record from a map 

For information about how to create a UI record from a map, see the 
"Record" section in this chapter. 
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Distributing text user interfaces on the Internet 

VisualAge Generator supports a distributed user interface, where the user 
interface is on one machine and the logic and data are on a server machine. 

You can access VisualAge Generator CICS text user interface (TUI) programs 
on the Internet by using the CICS Internet Gateway (CIG). In most cases, you 
do not have to change your program. 

VisualAge Generator also supports development of programs that have a 
Web-based user interface and can be generated for various platforms. For 
more information on building application systems with Web interfaces, see 
"Web Transaction" on page 47. 

Client systems 

The CIG is available with CICS Client for the following systems: 

• CICS for OS/2 

• CICS for AIX 

Server systems 

The CICS Client External Presentation Interface (EPI) supports the following 
VisualAge Generator CICS server systems. All VisualAge Generator TUI 
programs targeted for these server systems can be accessed on the Internet via 
CIG. 

• CICS for MVS/ESA V4.1 

• CICS for AIX 

• CICS for OS/2 

• CICS for Windows NT 

Accessing the Internet with CICS Internet Gateway 

The CIG uses the EPI interface provided with the CICS client. The EPI 
interface enables a program to catch the 3270 data stream that represents the 
TUI screen. CIG then converts the data stream to corresponding HTML 
(HyperText Markup Language) in a CGI script file. It acts as a screen 
conversion tool that makes TUI programs available to the Internet. By default, 
CIG adds a CIG graphical interface facility (GIF) heading and will map the 
function keys to push buttons on the bottom of the screen. 
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Figure 11. Sample CICS Terminal Screen 



Figure 11 shows a VisualAge Generator TUI running on CICS for OS/2 as a 
VisualAge Generator DB2 COBOL program. After converting the screen 
through CIG, the same TUI is displayed via the IBM Explorer WWW browser 
over the Internet. The CIG provides the basic CGI script to convert the 3270 
data stream to HTML. You can then wrap the default CGI script to customize 
the data stream before it reaches the Web Browser. 
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Figure 12. Sample Screen on the Internet 



Figure 12 shows the TUI after conversion and as it appears in presentation 
mode on the Web Browser. This GUI was customized by wrapping the default 
CGI script shipped with CIG using a REXX program on the Web Server. The 
REXX program parsed through the HTML and added the VisualAge 
Generator icon, heading, and customized push buttons. It is possible to add 
many features to your new or existing TUIs as the HTML passes through your 
wrapper. 
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Chapter 4. Developing MQSeries application systems 



Message queueing provides an alternative to remote procedure call 
communication between programs. With message queueing, programs 
communicate by writing to and reading messages from queues. 

Message Queue Interface (MQI) is an IBM specification of an application 
programming interface (API) for accessing message and queuing services that 
support data transfer between programs running on a wide variety of IBM 
and non-IBM platforms. The services allow programs to communicate without 
knowledge of the lower levels of the communication network and without 
knowledge of the location of the other programs. 

A message queue can be on the same system as a program (local) or on 
another system (remote). Queue managers manage access to queues and 
transmission of data between queues. 

An MQI message is a string of data sent from one program to another. An 
MQI message consists of program information and routing information used 
by the message queue manager (control information). The structure and content 
of the program information is determined by the communicating programs 
not by the queue manager. 

Programs that use message queueing techniques have the following features: 

• There is no physical connection between programs. 

• Communication network access functions are built into the queue 
managers, not into the programs. 

• Communicating programs can rim in parallel. 

• Communicating programs do not need to be running concurrently. 

• Intermittent communication link failures do not prevent messages from 
being delivered. 

• Work is carried out by small, self-contained programs. 

• Communication can be driven by events. 

• Messages can be assigned priorities. 

• Messages can be recoverable resources, committed or rolled back along with 
database or file updates. 

• Workloads can be balanced by starting multiple servers for processing a 
single queue. 

• Availability can be increased by assigning multiple alternative processors to 
service a queue. 
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IBM MQSeries products implement the message queue manager on a variety 
of run- time platforms: 

• MQSeries for OS/390 Version 2 Release 1 

• MQSeries for VSE/ESA Version 2 Release 1 

• MQSeries for OS/2 Warp Version 5 Release 1 

• MQSeries for Windows NT Version 5 Release 1 

• MQSeries for AIX Version 5 Release 1 

• MQSeries for AS/400 Version 4 Release 2.1 

• MQSeries for HP-UX Version 5 Release 1 

• MQSeries for Sun Solaris Version 5 Release 1 

For more information on message queueing and the design of message 
queueing programs, refer to the following documents: 

• An Introduction to Messaging and Queueing (GC33-0805-01) 

• MQSeries MQI Technical Reference (SC33-0850) 

• MQSeries Application Programming Guide (SC33-0807-10) 

• MQSeries Application Programming Reference (SC33-1673-06) 

MQ programs are programs that access MQSeries message queues. In 
previous releases, VisualAge Generator supported development of MQ 
programs that access message queues through direct calls to VisualAge 
Generator APIs. In the current release, VisualAge Generator supports access to 
message queues through the serial file I/O options, ADD and SCAN. MQ API 
calls are still supported for compatibility with the previous releases. New 
development should be done using the file level interface. The file interface is 
supported in all runtime environments (with the exception of CICS for OS/2 
and SCO OpenServer) and in all types of programs, including web 
transactions, GUIs, and 3270 and batch programs. 

Subsequent sections of this chapter discuss how to implement MQ programs 
using either the file level interface or direct MQ API calls. 



Implementing MQ programs using the file level interface 

Developing MQ programs that use the file level interface includes: 

• Using sample programs 

• Defining messages in VisualAge Generator 

• Specifying the message queue name 

• Specifying MQSeries options for messages and queues 

• Specifying default values for programs that access message queues 

• Connecting to queue managers 
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• Writing messages to queues 

• Reading messages from queues 

• Committing or rolling back messages 

• Handling errors 

• Using linkage tables for MQSeries run time library selection 

• Testing MQ programs 

• Triggering programs when messages are placed on queues 

Using sample programs 

You can use sample programs shipped with VisualAge Generator to 
understand how to implement MQ programs using the file level interface. 
Refer to VisualAge Generator Getting Started for information on accessing 
sample programs and documentation. 

Defining messages in VisualAge Generator 

In VisualAge Generator, you can use a message queue record to store 
MQSeries message structure definitions. The record data item structure is the 
message format. Message queue records are similar to working storage 
records. In a message queue record, you can define message attributes. For 
example, you can define whether a message is included in a transaction with 
other messages. You can also specify other MQSeries options for messages 
and queues. 

The fundamental components of messages defined in VisualAge Generator for 
MQSeries message queues are the message buffer, the application data, and 
message attributes. The message buffer is defined as a data item definition in 
a message queue record. Application data for message queue records is 
handled like application data for other record types. Message attributes are set 
or defined in the Message Queue Record Properties window of the Record 
Editor. 

Defining message attributes 

You can set or define the following message attributes in the Message Queue 
Record Properties window of the Record Editor: 

• File name 

• Alternate specification 

• Include message in transaction 

• Open queue for exclusive use on input 

• Record length item 

• Occurrences item 

You can also define MQSeries options for messages and queues. See the 
section on MQSeries options for more information. 
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In the File name field, type a one-to-eight character name. The file name is 
used to associate the record with the system resource name in the resource 
association file used during test or generation. The system resource name for 
message queue records defines the queue manager name and queue name. 
The file name is also the default system resource name if one is not specified. 
The system resource name is used as the initial value for the EZEDEST item 
for the message queue record and identifies the default queue associated with 
the record. By default, the File name field is blank and a file name is not 
specified. 

Note: File name is a required property. You cannot save a message queue 
record if a file name is not specified. 

If the record item structure for the record you are defining needs to be exactly 
the same as the record item structure already defined for another record, type 
the name of the other record in the Alternate specification field. Use the 
Alternate specification field to avoid creating and maintaining equivalent 
record structures. When you change the original record structure, you change 
the structure of all records that refer to it as an alternate specification. There is 
no record structure defined for this record. VisualAge Generator uses the 
structure defined in the record named as the alternate specification. By 
default, the Alternate specification field is blank and an alternate 
specification is not defined. 

Select Include message in transaction to include the message as a recoverable 
resource in the program's unit of work. If an input message is a recoverable 
resource, it is not removed from the input queue until the unit of work is 
commited. If the unit of work is rolled back, the input message remains on 
the input queue for processing by a later transaction. If an output message is 
a recoverable resource, it is not written to the output queue until the unit of 
work is commited. If the unit of work is rolled back, the output message is 
deleted. If the message is not part of the transaction, it is not affected by 
commit or rollback of the unit of work. Input messages are deleted from the 
input queue when read, and placed on the output queue when written. By 
default, the Include message in transaction field is selected and the message 
is sent to the queue when you issue a commit request. 

VisualAge Generator automatically opens the message queue associated with 
the message record whenever a VisualAge Generator program reads messages 
from the queue through the SCAN I/O option. Select Open queue for 
exclusive use on input if you want VisualAge Generator to open the queue 
for input for only one program at a time. Deselect Open queue for exclusive 
use on input if you want VisualAge Generator to open the queue for input 
for more than one program at a time. By default, the Open queue for 
exclusive use on input field is deselected and exclusive queue access is not 
specified. 
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In the Record length item field, type the name of the data item that defines 
message length. 

When a program adds the record to a message queue, the message length is 
set equal to the value in the record length item. When a program reads the 
message from the queue, the message length is returned in the record length 
item. 

If the record contains both a record length item and occurrences item, the 
record length item is set to the length calculated from the number of 
occurrences before a message is added to the queue. 

By default, the Record length item field is blank and a record length item is 
not defined. 

If the record you are defining ends with an array item that can have a 
variable number of occurrences, type the name of the data item whose value 
represents the actual number of occurrences at run time in the Occurrences 
item field. The value can range from 0 to the maximum number of 
occurrences for the array which is the occurs value specified for the array 
item. 

The occurrences item must meet all of the following requirements: 

• Be defined in the record before the array item 

• Have a numeric data type 

• Have a maximum length of 9 digits with 0 decimal places 

You do not need to specify the name of the array item. It is assumed to be the 
last multiply occurring item in the record. The array item can be 
substructured. The array item cannot be followed by another item at the same 
level in the record. 

When VisualAge Generator adds the message queue record to a message 
queue, the message length is calculated as the length of the record structure 
without the array plus the occurrences item value multiplied by the length of 
an array item. 

By default, the Occurrences item field is blank and an occurrences item is not 
defined. 

Specifying the message queue name 

Specify the queue name as the system resource name for the message queue 
record in the resource association file, or code the program to move the queue 
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name to the EZEDEST special function word for the message queue record. 
See the section on specifying default values for information on defining the 
resource association file. 

Queue name format is queue_manager_name:queue_name. The 
queue_manager_name: is optional. If omitted, the default queue manager is 
used. 

If not specified, the default queue name is the file name defined in the 
message queue record properties. 

Specifying MQSeries options for messages and queues 

You can specify MQSeries options for messages and queues that describe a 
message, the queue and how each is used. In VisualAge Generator, MQSeries 
options are defined through record definitions. Record definitions are 
specified in the properties window of a message queue record. You can 
specify the following definitions: 

• Queue descriptor record 

• Open options record 

• Message descriptor record 

• Get options record 

• Put options record 

You can also use an alternate specification of a working storage record in 
combination with MQSeries options for messages and queues. 

Queue descriptor record 

VisualAge Generator programs call the MQSeries MQOPEN and MQCLOSE 
functions to open and close queues associated with message queue records. 
The MQOD, MQ Object Descriptor, structure is a parameter on MQOPEN and 
MQCLOSE calls. 

If you do not specify a Queue descriptor record, VisualAge Generator 
automatically builds a default MQOD structure. VisualAge Generator sets all 
fields to initial values, except for the object type, queue manager name and 
queue name. VisualAge Generator sets the object type to MQOT_Q for the 
queue. VisualAge Generator sets the queue manager name and queue name to 
the current values specified in EZEDEST for the record. If the queue manager 
name is not specified in EZEDEST, then a value for OBJECTQMGRNAME is 
not specified. OBJECTQMGRNAME and OBJECTNAME values are critical 
when you want to change queue managers before putting or getting 
messages. 
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If you need to specify other MQOD options or access information returned in 
the MQOD structure, you can use the MQOD working storage record shipped 
with the sample MQ programs. 
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Figure 13. MQOD record definition 



You can specify MQOD or the name of an alternate specification of MQOD to 
automatically include the record you specify in your program. Code the 
program to initialize and set fields in the MQOD record before accessing the 
queue. VisualAge Generator uses your MQOD structure instead of the default 
structure. 



Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQOD structure. 

Open options record 

VisualAge Generator programs call the MQSeries MQOPEN and MQCLOSE 
functions to open and close queues associated with message queue records. A 
four-byte binary options field is one of the parameters on the MQOPEN and 
MQCLOSE calls. 

If you do not specify an Open options record, VisualAge Generator 
automatically builds a default options parameter. On an open for an ADD, the 
options parameter is set to MQOO_OUTPUT + MQOO_FAIL_IF_QUIESCING. 
On open for exclusive use for a SCAN, the options parameter is set to 
MQOO_INPUT_EXCLUSIVE + MQOO_FAIL_IF_QUIESCING. On open for 
shared use for a SCAN, the options parameter is set to 
MQOO_INPUT_SHARED + MQOO_FAIL_IF_QUIESCING. On close, the 
options parameter is set to MQCO_NONE. 
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If you need to specify other option values, you can use the MQOO working 
storage record shipped with the sample MQ programs. 
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Figure 14. MQOO record definition 



You can specify MQOO or the name of an alternate specification of MQOO to 
automatically include the record you specify in your program. Set options you 
need in the MQOO option item before opening and closing the queue. 
VisualAge Generator uses your MQOO options as the options parameter 
instead of the default options. 

Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQOPEN and MQCLOSE options. 

Message descriptor record 

VisualAge Generator programs call the MQSeries MQGET and MQPUT 
functions to implement the ADD and SCAN options for message queue 
records. The MQMD, MQ Message Descriptor, structure is a parameter on 
MQGET and MQPUT calls. 

If you do not specify a Message descriptor record, VisualAge Generator 
automatically builds a default MQMD structure. VisualAge Generator sets all 
the MQMD fields to their initial default values. 

If you need to set any MQMD fields to values other than the default values or 
access information returned in the MQMD structure, you can use the MQMD 
working storage record shipped with the sample MQ programs. 
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Figure 15. MQMD record definition 



You can specify MQMD or the name of an alternate specification of MQMD to 
automatically include the record you specify in your program. Code the 
program to initialize and set fields in the MQMD record before accessing the 
queue. VisualAge Generator uses your MQMD structure instead of the default 
structure. 



Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQMD structure. 

Get options record 

VisualAge Generator programs call the MQSeries MQGET function to 
implement the SCAN option for a message queue record. The MQGMO, MQ 
Get Message Options, structure is a parameter on the MQGET call. 

If you do not specify a Get options record, VisualAge Generator automatically 
builds a default MQGMO structure, setting the MQGMO_SYNCPOINT or 
MQGMO_NO_SYNCPOINT options based on whether you defined the 
message queue record to include the message in your transaction. 
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If you need to specify other get options or access information returned in the 
MQGMO structure, you can use the MQGMO working storage record shipped 
with the sample MQ programs. 



MQGMO - Record Editor 
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Figure 16. MQGMO record definition 



You can specify MQGMO or the name of an alternate specification of 
MQGMO to automatically include the record you specify in your program. 
Code the program to initialize and set options in the MQGMO record before 
scanning the queue. VisualAge Generator uses your MQGMO structure 
instead of the default structure. 



Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQGMO structure. 

Put options record 

VisualAge Generator programs call the MQSeries MQPUT function to 
implement the ADD option for a message queue record. The MQPMO, MQ 
Put Message Options, structure is a parameter on the MQPUT call. 

If you do not specify a Put options record, VisualAge Generator automatically 
builds a default MQPMO structure. VisualAge Generator sets the 
MQPMO_SYNCPOINT or MQPMO_NO_SYNC POINT options based on 
whether you defined the message queue record to include the message in 
your transaction. 

If you need to specify other put options or access information returned in the 
MQPMO structure, you can use the MQPMO working storage record shipped 
with the sample MQ programs. 
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a MQPMO - Record Editor 
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Figure 1 7. MQPMO record definition 



You can specify MQPMO or the name of an alternate specification of MQPMO 
to automatically include the record you specify in your program. Code the 
program to initialize and set options in the MQPMO record before adding any 
messages to the queue. VisualAge Generator uses your MQPMO structure 
instead of the default structure. 



Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQPMO structure. 

Alternate record specification and MQSeries options 

If you need more than one copy of an options record for use with different 
message queue records in the same program, you can define new records as 
alternate specifications of the options records. Alternate specification is a 
property of the new record definition that specifies that the record has the 
same data item definition as the record named in the property. 

Specifying default values for programs that access message queues 

You can define resource associations to specify default values for VisualAge 
Generator programs that access message queues. 

Use resource associations for: 

• Defining the queue manager name and queue name 

• Defining the system 

• Converting message formats 
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To define a resource associations part for message queues: 

1 . Create a resource association part. 

2. Specify the file name 

Specify the file name as shown in the following example: 
FILE=filename 

The entry will be used for any message queue record with the same file 
name. 

3. Specify the file type 

Set the file type as shown in the following example: 

/FILETYPE=MQ 

4. Specify the system resource name 

You should specify the system resource name as shown in the following 
example: 

/SYSNAME=queue_manager_name:queue_name 

or, specify only the queue_name if you want to use the default queue 
manager. 

The system resource name for message queue records defines the queue 
manager name and queue name. The system resource name is used as the 
initial value for the EZEDEST item for the message queue record and 
identifies the default queue associated with the record. 

VAGen uses the system resource name on ADD and SCAN I/O operations 
for the message queue record. The queue name identifies the queue that is 
accessed by the operation. The queue manager name identifies the queue 
manager on which the queue is defined. The default queue manager is the 
queue manager to which the program is connected. 

If there is not already an active connection, VAGen uses the queue 
manager name to connect to the queue manager before accessing the 
queue. If no queue manager name is specified, VAGen connects to the 
default queue manager for the system. 

If the system resource name is not specified in a resource association file, a 
default system resource name is defined by the File name property of the 
message queue record. 

5. Specify the system name 

Specify the system name as shown in the following example: 
/SYSTEM=system_name 

6. Specify a conversion table name if you want data format conversion to be 
performed on the message 
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If you want data format conversion to be performed on the message, 
specify a conversion table name as shown in the following example: 
/CONTABLE=conversi on_table_name 

Because of the differences in character and numeric data formats between 
environments, your program might have to convert data as it is passed 
between a local format, such as the client machine, and a remote format, 
such as the server machine running the message queue. In VAGen 
programs, you can convert data based on the data item definition of the 
parameters or record structures as defined to the program. 

The type of conversion required is defined using a VAGen conversion 
table. Implementation of conversion tables varies with the environment. 
Refer to the VisualAge Generator Client/Server Communications Guide for 
more information on conversion tables. 

If a conversion table is specified, VAGen converts the message from local 
format to remote format when the message is added to the queue, and 
from remote format to local format when the message is read from the 
queue. VAGen performs conversion using the message queue record 
structure to identify the data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the EZECONVT 
special function word. 

Connecting to queue managers 

You can connect to only one queue manager at a time in a VisualAge 
Generator program. 

VisualAge Generator automatically connects to the queue manager on the first 
ADD or SCAN in a program, using the queue manager name specified in the 
system resource name associated with the message queue record. If the queue 
manager name is not specified, the queue manager is the default queue 
manager defined for your system. VisualAge Generator automatically 
disconnects from the queue manager when the program ends, closing any 
open files and commiting the current unit of work if it is still open. 

If the connection queue manager and the queue manager to which the queue 
belongs are different, use the MQCONN reusable part to connect before 
issuing the ADD or SCAN in the program. The ADD or the SCAN will use 
the current open connection instead of attempting to connect to the queue 
manager specified in the system resource name. 
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If you want a long running program to disconnect from the queue manager 
before the program ends, use the MQCONN reusable part to do the initial 
connection and the MQDISC part to disconnect after all queue access is 
complete. 

The MQCONN and MQDISC parts are described in the section on using 
direct MQ API calls. In workstation environments (Windows NT, OS/2, AIX, 
Solaris, and HP), MQSeries provides different runtime libraries for MQ 
programs depending on whether the program is running on the same system 
as the message queue manager or whether the program is running as an MQ 
client communicating with a manager on a server system. On AIX and HP 
systems, different libraries are provided for threaded and non-threaded 
environments as well. 

Writing messages to queues 

The process for writing messages to queues depends on whether you want to 
write messages to queues on the same queue manager or write messages to 
queues on different queue managers. In both cases, you can write messages to 
queues using the ADD I/O option with the message queue record as the I/O 
object. 

You can write messages to queues on the same queue manager using the 
ADD I/O option. When you use the ADD I/O option, Visual Age Generator: 

1 . Establishes the connection to the queue 

2. Opens the connection to the queue 

3. Puts the message on the queue 

You can write messages to a queue on another Queue Manager using the 
ADD I/O option. If you previously wrote a message to a queue using the 
ADD I/O option, you must use a local definition of the remote queue on the 
currently connected queue manager. 

Visual Age Generator saves the connection handle for future ADD calls. 

You must use the CLOSE I/O option after an ADD call to close the connection 
to the queue: 

• Before using the SCAN I/O option 

• To release the queue for access by another program 

• To release the queue if you have a long running program and have 
completed work with the queue 

VisualAge Generator automatically closes the connection to the queue on 
program termination. 
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Reading messages from queues 

The process for reading messages from queues depends on whether you want 
to read messages from queues on the same queue manager or read messages 
from queues on different queue managers. In both cases you can use the 
SCAN I/O option with the message queue record as the I/O object to read a 
message. 

You can read messages from queues on the same queue manager using the 
SCAN I/O option. When you use the SCAN I/O option, Visual Age 
Generator: 

1 . Connects to the queue manager, if the queue manager is not already 
connected 

2. Opens the queue, if the queue is not already open 

3. Gets the next message from the queue 

You can read messages from queues on different queue managers using the 
SCAN I/O option. If you previously read a message from a queue using the 
SCAN I/O option, you must use a local definition of the remote queue on the 
currently connected queue manager. 

You must use the CLOSE I/O option after a SCAN call to close the connection 
to the queue: 

• Before using the ADD I/O option 

• To release the queue for access by another program 

• To release the queue if you have a long running program and have 
completed work with the queue 

VisualAge Generator automatically closes the connection to the queue on 
program termination. 

Committing or rolling back messages 

When you combine messages in a transaction that defines a unit of work 
(UOW), the messages can be committed or rolled back as a group. When a 
UOW is committed, everything included in the transaction is finalized. When 
a UOW is rolled back, everything included in the transaction is removed. 

The methods used for commits and rollbacks depend on your environment. 
The following environments handle commits and rollbacks independently of 
MQSeries: 

• AS/400 

• CICS for MVS/ESA 

• CICS for VSE/ESA 

• IMS 
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In these transaction environments, message queue commits and rollbacks are 
coordinated with commits and rollbacks for other recoverable resources, like 
DB2 databases, using a two-phase commit protocol. 

In other environments, the resources for different managers are committed 
independently from one another. VisualAge Generator automatically issues 
the appropriate MQSeries calls for commits and rollbacks when you use 
EZECOMIT and EZEROLLB. 

Handling errors 

You can use VisualAge Generator support for automated error handling or 
custom error handling. You can select automated error handling by setting 
EZEFEC to 0 or custom error handling by setting EZEFEC to 1. 

Error handling involves the following types of errors: 
Hard errors 

Errors that cause the program to abnormally end 
Soft errors 

Errors that do not cause the program to abnormally end 
Handling hard errors 

There are considerations for automated and custom error handling of hard 
errors. 

If you enable automated error handling by setting EZEFEC to 0 and a hard 
error is encountered during an ADD or CLOSE operation, the error is handled 
differently based on your environment. On the workstation, VisualAge 
Generator sets the CMCOMP structure and terminates the program. On host 
systems, VisualAge Generator calls error services to handle the error. 

If you enable custom error handling by setting EZEFEC to 1 and a hard error 
is encountered during an ADD or CLOSE operation, VisualAge Generator 
sets: 

• EZERT2 with the completion code 

• EZERT8 with the reason code 

• The I/O error value for the message queue record 

After VisualAge Generator returns the completion code, reason code and I/O 
error value, program execution continues. 

Use conditional coding in your program based on the MQSeries reason codes 
to handle hard errors. For hard errors when EZEFEC is set to 1, MQSeries 
reason codes are written to EZERT8. 
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Handling soft errors 

If a soft error occurs on an ADD, SCAN or CLOSE due to MQSeries reason 
codes MQRC_TRUNCATED_MSG_ACCEPTED or 

MQRC_NO_MSG_ AVAILABLE, VisualAge Generator will not terminate the 
program. 

Use conditional coding in your program based on the MQSeries reason codes 
to handle soft errors. For soft errors, MQSeries reason codes are written to 
EZERT8. 

Using linkage tables for MQSeries run time library selection 

Use a VisualAge Generator linkage table part to indicate which runtime 
library you want to use. The MQ reusable parts shipped with VisualAge 
Generator include sample linkage tables for all supported environments. The 
following table shows which linkage table part to use in each environment. 
You can use the linkage table parts directly, or copy the entries in the parts to 
your own linkage table, if you need to specify entries for other program calls. 



Table 8. Linkage Tables for MQ Programs 



Environment 


MQSeries Library 
Description 


MQSeries Library 


Wrapper DLL 
Name 


Linkage Table 


Windows 


MQ manager 


mqm.lib 


csomqm32 


mqm32.1kg 


Windows 


MQ client 


mqic32.1ib 


csomqc32 


mqic32.1kg 


OS/2 


MQ manager 


mqm.lib 


csomqm 


mqm.lkg 


OS/2 


MQ client 


mqic.lib 


csomqic 


mqic.lkg 


AIX 


MQ manager 


libmqm.a 


csomqm 


libmqm.lkg 


AIX 


MQ client 


libmqic.a 


csomqic 


libmqic.lkg 


AIX 


MQ manager, 

threaded 

environment 


libmqm_r.a 


csomqmr 


libmqm_r.lkg 


AIX 


MQ client, threaded 
environment 


libmqic_r.a 


csomqicr 


libmqic_r.lkg 


HP-UX 


MQ manager 


libmqm.sl 


csomqm 


libmqm.lkg 


HP-UX 


MQ client 


libmqic.sl 


csomqic 


libmqic.lkg 


HP-UX 


MQ manager, 

threaded 

environment 


libmqm_r.sl 


csomqmr 


libmqm_r.lkg 


HP-UX 


MQ client, threaded 
environment 


libmqic_r.sl 


csomqicr 


libmqic_r.lkg 


Solaris 


MQ manager 


libmqm.so 


csomqm 


libmqm.lkg 


Solaris 


MQ client 


libmqic.so 


csomqic 


libmqic.lkg 
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If you are testing or running with an MQ manager, non-threaded library, 
specify the linkage table part as a test or generation option. If you are testing 
or running with an MQ client or threaded library, you must also move the 
part to a file and set the CSOLINKTBL environment variable to the file name. 

Generated Java programs require a special format for the linkage table entry. 
The entry should look like the following: 

: cal 1 1 i nk appl name=el aq* 1 ibrary=mq_wrapper_dl l_name 1 i nktype=csocal 1 

parmform=commptr remotecomtype=di rect remoteapptype=nonvg 
contabl e=java_conversi on_tabl e_name 

where the mq_wrapper_dll is the wrapper dll name for your runtime 
environment from the previous chart, and the java_conversion_table_name is 
the java conversion table correct for your language and the system on which 
the program is running. Refer to the VisualAge Generator Client /Server 
Communications Guide for help in determining which conversion table to 
choose. 

Testing MQ programs 

You can use the test facility to develop and test almost all MQ program logic. 
Define and debug the logic of both client and server programs using the 
VisualAge Generator test facility and local OS/2 queues. After the program 
logic is validated, you can generate for the appropriate run-time environments 
and perform the final production test with remote queues and local message 
queues. 

Before you can begin testing an MQ program, you need to define resource 
associations. 

To define resource associations in the VisualAge Generator test facility for 
message queues: 

1 . Select Tools-»Resource Associations File. In the Resource Association File 
Window, select the Add button. 

2. Specify the file name 

Type the file name in the Logical name field of the Primary Specification 
Window. The entry will be used for any message queue record with the 
same file name. 

3. Specify the file type 

Select Message Queue in the Organization field of the Primary 
Specification Window. 

4. Specify the system resource name 

Type the queue manager name and queue name in the Physical name 
field of the Primary Specification Window as shown in the following 
example: 
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queue_manager_name:queue_name 

The system resource name for message queue records defines the queue 
manager name and queue name. The system resource name is used as the 
initial value for the EZEDEST item for the message queue record and 
identifies the default queue associated with the record. 

VAGen uses the system resource name on ADD and SCAN I/O operations 
for the message queue record. The queue name identifies the queue that is 
accessed by the operation. The queue manager name identifies the queue 
manager on which the queue is defined. The default queue manager is the 
queue manager to which the program is connected. 

If there is not already an active connection, VAGen uses the queue 
manager name to connect to the queue manager before accessing the 
queue. If no queue manager name is specified, VAGen connects to the 
default queue manager for the system. 

If the system resource name is not specified in a resource association file, a 
default system resource name is defined by the File name property of the 
message queue record. 

5. Specify a conversion table name 

If you want data format conversion to be performed on the message, type 
a conversion table name in the Physical name field of the Primary 
Specification Window. 

Because of the differences in character and numeric data formats between 
environments, your program might have to convert data as it is passed 
between a local format, such as the client machine, and a remote format, 
such as the server machine running the message queue. In VAGen 
programs, you can convert data based on the data item definition of the 
parameters or record structures as defined to the program. 

The type of conversion required is defined using a VAGen conversion 
table. Implementation of conversion tables varies with the environment. 
Refer to the VisualAge Generator Client/Server Communications Guide for 
more information on conversion tables. 

If a conversion table is specified, VAGen converts the message from local 
format to remote format when the message is added to the queue, and 
from remote format to local format when the message is read from the 
queue. VAGen performs conversion using the message queue record 
structure to identify the data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the EZECONVT 
special function word. 

6. Click the OK button and close the Resource Association File Window. 
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When testing with MQ, make sure to specify the linkage table appropriate for 
your environment in the VAGen Test Linkage Preferences. 

Triggering programs when messages are placed on queues 

Some MQSeries applications that serve queues run continuously so they are 
always available to retrieve messages that arrive on the queues. However, this 
may not be desirable when the number of messages arriving on the queues is 
unpredictable. In this case, applications could be consuming system resources 
even when there are no messages to retrieve. 

MQSeries provides a facility that enables an application to be started 
automatically when there are messages available to retrieve. This facility is 
known as triggering. 

Refer to the MQSeries Application Programming Guide (SC33-0807-10) for 
information on the following topics: 

• What is triggering? 

• Prerequisites for triggering 

• Conditions for a trigger event 

• Controlling trigger events 

• Designing an application that uses triggered queues 

• Trigger monitors 

• Properties of trigger messages 

• When triggering does not work 

Refer to MQSeries Intercommunication (SC33-1872-03) for information about 
triggering channels. 



Implementing MQ programs using direct MQ API calls 

Developing VisualAge Generator programs that use direct MQ API calls 
includes: 

• Using sample programs 

• Defining messages in VisualAge Generator 

• Specifying MQSeries options for messages and queues 

• Connecting to queue managers 

• Converting message formats 

• Writing messages to queues 

• Reading messages from queues 

• Committing or rolling back messages 

• Handling errors 

• Specifying linkage tables for MQ programs 

• Testing MQ programs 
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Using sample programs 

The MQI is a set of program interfaces used to request services from the 
message queue manager. The following functions are supported: 

• Connecting and disconnecting from the queue manager (MQCONN or 
MQCONNX, MQDISC) 

• Opening and closing a queue (MQOPEN, MQCLOSE) 

• Reading a message from a queue (MQGET) 

• Writing a message to a queue (MQPUT) 

• Writing a single message to a queue with an implicit open and close of the 
queue (MQPUT1) 

• Requesting or setting attributes of a queue manager object such as a queue 
(MQINQ, MQSET) 

• Beginning a unit of work (MQBEGIN) 

• Committing or backing out changes (MQCMIT, MQBACK) 

VisualAge Generator provides sample functions that call the appropriate entry 
point on the workstation or mainframe. The sample functions have the same 
name as the MQAPI that they call. For example, the function that calls the 
MQPUT API is name MQPUT. The functions assume the parameters are 
defined and initialized using the sample records. The groups and parameter 
definitions can be reused in any MQ program definition. 

Four sample programs show how to use MQI calls manually within 
VisualAge Generator batch, 3720, GUI and Web client programs. The 
programs use common record and function definitions for calling MQI entry 
points. The sample programs can be loaded from the following .dat files: 

• For VisualAge Generator Developer on Smalltalk, 
c:\Program FilesWAST\samples\MQS.DAT ( for NT) or 
c:\VAST\samples\MQS.DAT (for OS2): contain the Smalltalk application 
HptSampleMQApp. See VisualAge Generator Getting Started for detailed 
information on importing and loading applications. 

• For VisualAge Generator Developer on Java, 
IBMVJava\IDE\program\samples\MQJ.DAT contains the Java 
project\ package VAGen MQ SampleXibm.com.vgj.sample.mq. See 
VisualAge Generator Getting Started for detailed information on importing 
and loading projects and packages. 

MQ3270 - VisualAge Generator MQI sample program for 3270 
environments 

You can use MQ3270 to write and read messages from a queue. The messages 
are deleted when you read them. Messages are typed and displayed in an 
array on a 3270 map. 
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Enter the message queue manager name and the message queue name in the 
map before reading or writing messages. 

The following keys are supported: 
F3/F12 Quit 

F8 Read and display up to 10 messages from the queue. When a message 
is read, it is removed from the queue. 

F9 Write any messages currently in the message array on the screen to 
the queue. 

MQGUI and MQWEB - VisualAge Generator MQI sample programs for GUI 
and Web environments 

You can use MQGUI or MQWEB to write and read messages from a queue. 
The messages are deleted after you read them. 

You must enter the message queue manager name and the message queue 
name in the window before reading or writing messages. 

The following pushbuttons are supported: 
Quit Leave the program. 
Get Messages 

Read and display up to 20 messages in a table on the window. 
Put Messages 

Write the message text that is in the window's Message to put to 
queue field to the queue. Repeat the write operation for the repetition 
count entered on the window. 

MQBATCH - VisualAge Generator MQI sample batch program 

MQBATCH tests each MQI function and prints a simple report to the 
EZEPRINT file. This report indicates whether the functions completed 
successfully. MQBATCH uses the default queue manager and requires a queue 
named TESTQUEUE with a message length of at least 100 characters. 

Four tests are performed: 
Put/Get 

Writes a single message to TESTQUEUE and reads it back 
Commit 

Verifies that commit and rollback functions work with messages in 
supported environments 

Inquiry 

Exercises the inquiry function to retrieve queue attributes 
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Set Exercises the set function to prevent writes to TESTQUEUE and 
verifies that the function was effective 



Reusable parts from the sample programs 

Parameter definitions: MQI parameters are either data items or records. 
Refer to the MQSeries MQI Technical Reference for a complete description of the 
MQI parameters. 

MQSTATE and MQ ATTRIBUTES, sample records, contain declarations for 
most data item parameters. Parameter names are the same as in the parameter 
declarations shown in the MQSeries MQI Technical Reference 

The BUFFER parameter (message buffer parameter used with MQGET, 
MQPUT, and MQPUT1 calls) and the CHARATTRS (character attributes buffer 
parameter used with MQINQ and MQSET calls) are both defined with a 
length of 1024 characters. Increase the length of these items if you reuse 
MQSTATE in a program that requires larger buffers. 

Data structures: Sample records are provided to define the format of record 
parameters and special purpose messages and message headers. Record 
names are the same as the COBOL and C structure names. The data items in 
the records have the same names as the corresponding fields in the COBOL 
and C structures, except that the COBOL names use a hyphen (-) as a token 
separator instead of an underscore. 

The following is a list of structure records: 
MQBO 

Begin options 

MQCNO 

Connect options 

MQDH 

Distribution header 

MQDLH 

Dead-letter header 

MQGMO 

Get-message options parameter 

MQINTATTRS 

Integer attributes parameter 

MQMD 

Message descriptor parameter 
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MQMD1 

Message descriptor (version 1) 

MQMDE 

Message descriptor extension 

MQOD 

Object descriptor parameter 

MQOR 

Object record 

MQPMO 

Put-message options structure 

MQRMH 

Message reference header 

MQRR 

Response record 

MQSELECTORS 

Attribute selectors parameter 

MQTM 

Trigger message structure 

MQTMC2 

Trigger message 2 (character format) 

MQXQH 

Transmission queue header 

Functions for initializing structure parameters: The following sample 
functions can be used to initialize structure parameter fields to their default 
values: 

MQBO_INIT 

Initialize begin options 

MQCNOJNIT 

Initialize connect options 

MQDHJNIT 

Initialize distribution header 

MQDLH_INIT 

Initialize dead-letter header structure 

MQGMO_INIT 

Initialize get-message options structure 

MQMDJNIT 

Initialize message descriptor structure 
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MQMD1JNIT 

Initialize message descriptor (version 1) 

MQMDE_INIT 

Initialize message descriptor extension 

MQOD_INIT 

Initialize object descriptor structure 

MQOR_INIT 

Initialize object record 

MQPMO_INIT 

Initialize put-message options structure 

MQRMH_INIT 

Initialize message reference header 

MQRRJNIT 

Initialize response record 

MQSTATEJNIT 

Initialize item parameters and system state values 

MQTM_INIT 

Initialize trigger message structure 

MQTMC2_INIT 

Initialize trigger message 2 (character format) 

MQXQHJNIT 

Initialize transmission queue header structure 

Functions for calling MQSeries APIs: The following sample functions can 
be used to call MQSeries APIs: 

MQCONN 

Connect to message queue manager 

MQCONNX 

Extended connect 

MQDISC 

Disconnect from message queue manager 

MQOPEN 

Open a message queue 

MQCLOSE 

Close a message queue 

MQGET 

Read a message from a queue 
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MQPUT 

Write a message to a queue 

MQPUT1 

Write a single message to a queue including queue open and close 

MQINQ 

Inquire about queue attributes 

MQSET 

Set queue attributes 

MQBEGIN 

Begin a logical unit of work 

MQCMIT 

Commit a logical unit of work 

MQBACK 

Back out a logical unit of work 

Constants and return codes: The values for MQ parameters are set using 
constants. In the sample programs, constant values are defined in table 
MQVALUE and return codes in table MQRC. Another table, MQRCODE, is 
used in the sample programs as a look-up table that associates a return code 
with the return code description. 

The VisualAge Generator constants and return codes have the same names as 
the MQI constants defined for C or COBOL. Like the C constants, the 
VisualAge Generator version of the constant names uses an underscore^) 
instead of a hyphen(-) as a token separator in the constant name. 

One constant, MQENC -NATIVE (numeric encoding format for current 
environment), is defined as a data item in the MQSTATE working storage 
record. The MQSTATE JNIT function sets the value of MQENC-NATIVE 
based on the system on which the program is running. 

Defining messages in VisualAge Generator 

The two fundamental components of messages defined in an MQ program 
that uses direct MQ API calls are the message buffer and application data. The 
message buffer is defined as a data item definition in a working storage 
record. The application data is defined explicitly or implicitly through 
functions. 

Use working storage records to store MQSeries message structure definitions. 
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Defining message buffers 

You can define message buffers for manual MQI calls by creating data item 
definitions in working storage records. Data item definitions can be shared 
with other working storage records or used exclusively by a single record. 

Defining application data 

You can define application data explicitly or implicitly. 

You can define application data explicitly by assigning values to data items 
that represent message buffers. Assign a value in a function to a data item 
defined in a working storage record. For example, if you define a working 
storage record with a data item named col ors, you could define the 
application data explicitly with the following code in a function: 
colors="red, green and blue"; 

In this example the message buffer is defined as a data item named col ors 
and the application data is defined explicitly as red, green and blue. 

You can define application data implicitly by assigning values from data items 
to data items that represent message buffers. Assign a value in a function to a 
data item defined in a working storage record. For example, if you define a 
message queue record with a data item named col ors, and you have a data 
item named primary that contains the literal string red, green and blue; you 
could define the application data implicitly with the following code in a 
function: 

col ors=primary ; 

In the example, the message buffer is colors and the application data is 
defined as red, green and blue, a literal string passed into the message 
buffer from a data item named primary. 

Specifying MQSeries options for messages and queues 

You can specify MQSeries options for messages and queues that describe a 
message, the queue and how each is used. In VisualAge Generator, MQSeries 
options are manually defined through function definitions. 

Values for MQI options are set using constants from the MQVALUE table. 

To specify an option to MQI, code a statement to assign the constant to the 
appropriate options variable. 

For example, to indicate open for output, code: 
MQSTATE. OPTIONS = MQ00_0UTPUT ; 

To set multiple options, assign the sum of the constants to the options 
variable, as shown below: 
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MQGMO .GETOPTIONS = MQGMO_LOCK 

+ MQGMO_ACCEPT_TRUNCATED_MSG 
+ MQGMO_BROWSE_FIRST ; 

Connecting to queue managers 

You can connect to only one queue manager at a time in a VisualAge 
Generator program. 

You connect to a queue manager with an MQCONN call in a function. If you 
want to use the default queue manager, leave the queue manager name field 
blank when you define the MQCONN call. 

Converting message formats 

The format of the program message data is not known to the message queue 
manager. Format conversion for program message data is the responsibility of 
the program. VisualAge Generator programs can use the EZECONV function 
in environments where it is supported to perform format conversion. 

To determine if message format conversion is required, a program can check 
the CodedCharSetld field (character set) and Encoding field (numeric data 
formats) in the message descriptor to determine if conversion is required. 

To avoid numeric field conversions altogether for VisualAge Generator 
programs, use packed decimal for numeric fields in messages. 

Writing messages to queues 

The process for writing messages to queues depends on whether you want to 
write messages to queues on the same queue manager or write messages to 
queues on different queue managers. In both cases you can use MQSeries calls 
to manually write messages to queues. 

Note: You must close and disconnect from the queue manually after the final 
MQPUT of the transaction. 

You can write messages to queues on the same queue manager manually 
using MQSeries calls: 

1 . Connect to the queue using MQCONN 

When you write a message to a queue, you can: 

• Include the message in a transaction 

• Exclude the message from a transaction 

2. Open a connection to the queue using MQOPEN 

3. Write a message to the queue using MQPUT 

4. Close the queue using MQCLOSE 

5. Disconnect from the queue using MQDISC 
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Disconnect from the queue when you want to commit the transaction and 
separate the transaction from any future calls. 

You can write messages to queues on different queue managers manually 
using MQSeries calls. If you previously wrote messages to queues manually 
using MQSeries calls, you must disconnect from the currently connected 
queue manager before writing a message to a queue on another queue 
manager. 

Once you disconnect from the queue manager using MQDISC, you can write 
a message to a queue on a new queue manager using the MQSeries calls: 
MQCONN, MQOPEN, MQPUT, MQCLOSE and MQDISC. 

Reading messages from queues 

The process for reading messages from queues depends on whether you want 
to read messages from queues on the same queue manager or read messages 
from queues on different queue managers. In both cases you can use 
MQSeries calls to manually read messages from queues. 

Note: You must close and disconnect from the queue explicitly after the final 
MQGET of the transaction. 

You can read messages from queues on the same queue manager using 
MQSeries calls: 

1 . Connect to the queue using MQCONN 

When you write a message to a queue, you can: 

• Include the message in a transaction 

• Exclude the message from a transaction 

2. Open a connection to the queue using MQOPEN 

3. Write a message to the queue using MQGET 

4. Close the queue using MQCLOSE 

5. Disconnect from the queue using MQDISC 

Disconnect from the queue when you want to commit the transaction and 
separate the transaction from any future calls. 

You can read messages from queues on different queue managers manually 
using MQSeries calls. If you previously read a message from a queue 
manually using MQSeries calls, you must manually disconnect from the 
currently connected queue manager before reading a message from a queue 
on another queue manager. 

Once you disconnect from the queue manager using MQDISC, you can read a 
message from a queue on a new queue manager using the MQSeries calls: 
MQCONN, MQOPEN, MQGET, MQCLOSE and MQDISC. 



Chapter 4. Developing MQSeries application systems 105 



Committing or rolling back messages 

Messages are treated as recoverable resources if the MQGMO-SYNCPOINT 
option is set for a message get request or if the MQPMO-SYNCPOINT request 
is set for a message put request. 

In transactional environments, messages are committed or rolled back in 
conjunction with other recoverable resources using the transaction manager 
two-phase (IMS/VS, IMS BMP, and all CICS environments) or single-phase 
(OS/400) commit protocol. In these environments, VisualAge Generator 
commit or rollback requests result in a commit or rollback of recoverable 
messages as well as file and database updates. 

In non-transactional environments (MVS TSO, MVS batch, IMS BMP, DL/I 
batch, VSE batch, and non-CICS environments), the only way to explicitly 
commit and back out recoverable messages is to use the MQCMIT and 
MQBACK MQI calls. An MQDISC or a normal end also results in a commit; 
abnormal termination of the region results in a rollback. The commit is a 
single-phase commit, and it is not coordinated with the VisualAge Generator 
commit or rollback functions for database. 

In the non-transaction environments, if a VisualAge Generator program 
terminates early because of an error condition that is detected by host 
run-time services, the VisualAge Generator automatic rollback does not affect 
recoverable messages, and program code cannot issue MQBACK. To ensure 
message rollback in this case, code the VisualAge Generator program as a 
called program, start the VisualAge Generator program with a call from a 
non- VisualAge Generator stub, and issue a MQBACK call in the 
non- VisualAge Generator stub if the VisualAge Generator program returns 
with a return code ^ 512 (abnormal termination detected by run-time 
services). The MQCONN and MQDISC calls should also be issued from the 
stub. 

To avoid problems with loosing messages, design workstation programs to do 
a destructive message get only after the message has been completely 
processed. 

You can use the MQCMIT and MQBACK functions in any environment. 

Handling errors 

Each MQI API function returns a completion code and reason code. In 
addition, each sample function that calls an MQI function builds a reason 
description in MQSTATE.REASON-DESCRIPTION. The reason description 
includes the API function name, the reason code in decimal, and mnemonic 
associated with the reason code in the MQSeries manuals. The reason 
description can be used in logging the error or reporting the error to the user, 
as is shown in the sample programs. 
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Specifying linkage tables for MQ programs 

On workstations, the MQ sample programs call MQ APIs via VisualAge 
Generator wrapper programs that are prelinked with MQSeries product 
libraries. In order to test or generate MQ programs, you must specify the 
linkage table appropriate for your environment and the MQSeries product 
library that you want to use. The following linkage tables are included when 
you load the sample MQ applications: 



Table 9. Linkage Tables for MQ Programs 



Environment 


MQSeries Library 
Description 


MQSeries Library 


Wrapper DLL 
Name 


Linkage Table 


Windows 


MQ manager 


mqm.lib 


csomqm32 


mqm32.1kg 


Windows 


MQ client 


mqic32.1ib 


csomqc32 


mqic32.1kg 


OS/2 


MQ manager 


mqm.lib 


csomqm 


mqm.lkg 


OS/2 


MQ client 


mqic.lib 


csomqic 


mqic.lkg 


AIX 


MQ manager 


libmqm.a 


csomqm 


libmqm.lkg 


AIX 


MQ client 


libmqic.a 


csomqic 


libmqic.lkg 


AIX 


MQ manager, 

threaded 

environment 


libmqm_r.a 


csomqmr 


libmqm_r.lkg 


AIX 


MQ client, threaded 
environment 


libmqic_r.a 


csomqicr 


libmqic_r.lkg 


HP-UX 


MQ manager 


libmqm.sl 


csomqm 


libmqm.lkg 


HP-UX 


MQ client 


libmqic.sl 


csomqic 


libmqic.lkg 


HP-UX 


MQ manager, 

threaded 

environment 


libmqm_r.sl 


csomqmr 


libmqm_r.lkg 


HP-UX 


MQ client, threaded 
environment 


libmqic_r.sl 


csomqicr 


libmqic_r.lkg 


Solaris 


MQ manager 


libmqm.so 


csomqm 


libmqm.lkg 


Solaris 


MQ client 


libmqic.so 


csomqic 


libmqic.lkg 



Testing MQ programs 

You can use the test facility to develop and test almost all MQ program logic. 
Define and debug the logic of both client and server programs using the 
VisualAge Generator test facility and local OS/2 queues. After the program 
logic is validated, you can generate for the appropriate run-time environments 
and perform the final production test with remote queues and local message 
queues. 
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If you are testing programs that commit or rollback messages, use the 
MQBEGIN function to start recoverable transactions. The MQBEGIN function 
conditionally calls the MQBEGIN API only in environments that support this 
call (Windows NT, OS/2, AIX, HP-UX, and Solaris). Because of the 
conditional call, you can leave the MQBEGIN function in programs generated 
for transactional and host environments that do not require (or support) 
MQBEGIN for starting transactions. 

When testing with MQ, make sure to specify the linkage table appropriate for 
your environment in the VAGen Test Linkage Preferences. 
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Chapter 5. Testing VAGen parts 

This chapter describes the tasks you will need to perform to test your 
application system. Testing of most VAGen parts is accomplished by using the 
VAGen Interactive Test Facility. If you are building a GUI client application, 
refer to the VisualAge for Java online help for more information about testing. 



Using the Test Monitor 

Test your VAGen application systems using the Interactive Test Facility (ITF). 
This section describes tasks you perform to control tests using the Test 
Monitor to control and briefly discusses other features of ITF that let you view 
specific information as you test. 

Testing VAGen parts 

The test facility enables you to test programs before generating them. You can 
test a partial program, debug that part, and continue defining the program. To 
test programs, you will need to do some of the following tasks. 

Setting test options 

To set test options: 

1 . From the VAGen Parts Browser, select the Window menu, then Options. 

2. Select one or more of the following to set the appropriate specifications. 

• Select Test to set general options and test values for EZEUSRID and 
EZESYS. 

• Select Test Linkage to specify a linkage table part and any programs 
you want bypassed when you test. 

• Select Test Trace to control what information is displayed in your trace 
log and select the type of messages displayed when you test. 

Monitoring the test 

The Test Monitor window provides textual monitoring of the current program. 

The following topics outline different ways to monitor a test. 

• Using the Test Monitor window 

• Using the Data View window 

• Using the Trace Log window 

Using the Test Monitor window 

As you run a test, information is displayed in the three panes (monitors) of 
the Test Monitor window. Initially, the Execution Stack Monitor, Watchpoint 
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Monitor, and the Statement Monitor are displayed. You can display all of the 
monitors at once or just one or two of them. 

To expand and collapse monitors in the Test Monitor window, select the 
collapse button on the split bar. To hide all monitors, from the View menu, 
select Hide All Monitors. 

Each monitor displays a different kind of information. Use the following 
definitions to help you configure your view. 

Execution Stack Monitor 

Shows the execution stack in a list. The top entry of the list is the 
name of the function that is running. Statements are displayed in the 
Statement Monitor as they are executed. The next entry in the list is 
the name of the function from which the current function was started. 
If the current function is in a called program, the functions of the 
calling program are displayed further down in the list. 

Watchpoint Monitor 

Shows the names and contents of any data elements on which you 
have set watchpoints. The contents of the data elements are updated 
dynamically as the program runs. 

Statement Monitor 

Shows the statements of a function, the flow statements associated 
with a main function, or the program components list. Each statement 
is highlighted as it rims. 

Viewing and changing data 

A Data View window presents a snapshot of the state of data elements at the 
moment you open the Data View window. The contents displayed are not 
updated. The Data View window automatically closes when the program 
resumes running. 

To open a Data View window: 

1 . From the Tools menu, select Program Data. 

2. On the Program Data window, do one of the following: 

• Double-click on an entry in the list. 

• Select an entry in the list, then select Browse. 

The Data View window appears showing the contents of the selected 
entry. 

The Data View window shows data elements, including every substructure 
level when the data elements are records. If the entry selected on the Program 
Data window is the placeholder entry for implicit data items, all the implicit 
data items in the program are listed in the Data View window. 
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You can also view the contents of any data element in the current program at 
any time by doing the following: 

• From the Tools menu, select Show Data. 
Modifying data values 

To modify the contents of a data element, on the Data View window, do the 
following: 

1 . Select a data element. 

2. Select Update. 

3. On the Move Data window, specify the new value in the Source field, then 
select OK. 

To modify the contents of a data element in the Watchpoint Monitor on the 
Test Monitor window, do one of the following: 

• Double-click on the data element in the Watchpoint Monitor. 

• From the Tools menu, select Move Data. You can do this at any time 
during the test. 

Note: You can modify only the data elements in the current program. If the 
data element you want to modify is not in the current program, you 
can use the Execution Stack Monitor to reposition the statement 
pointer to the program containing the data element. 

Using expanded view and occurrences view 

To view the complete specification, or the entire contents of the data element: 

1 . Select the data element in the Data View window. 

2. Select Expand 

The entire contents of the data element appear in the Expanded Data View 
window. You cannot modify the values of the data element in the Expanded 
Data View window. 

To view all occurrences of the data element that is an array, select the data 
element; then select Occurs. 

Using the Trace Log window 

In the Trace Log window, you can view the trace entries that have been 
collected during the test. You can have any number of Trace Log windows 
open, and you can tailor each Trace Log window to display specific types of 
trace entries. 
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To change the types of trace entries that are displayed, from the Options 
menu, select Set Filters. 

You can work with trace entries in the following ways: 

Saving trace entries 

To save the contents of the Trace Log window in a file, on the Trace 
Log window, from the File menu, select Save As. 

Printing trace entries 

To print trace entries, select the trace entries you want to print; then 
from the File menu, select Print. If you want to print all of the trace 
entries, from the Edit menu, select Select All. 

Copying trace entries 

To copy trace entries, select the trace entries you want to copy; then, 
from the Edit menu, select Copy. If you want to copy all of the trace 
entries, from the Edit menu, select Select All. 

You can then copy the trace entries into a file using a text editor. 

Setting filters 

To set filters on the types of trace entries that you want to appear in 
the Trace Log window, from the Options menu, select Set Filters. 

Refreshing the trace entries 

To update the collected trace entries in the Trace Log window, based 
on the new trace entry filters you have set for that window, from the 
Options menu, select Refresh. 

Repositioning the statement pointer 

When the test is suspended, you can reposition the statement pointer to 
change the point where the test resumes. 

To reposition the statement pointer: 

• Select an entry in the Statement Monitor; then, select Confirm Reposition. 
The selected statement rims next. 

• Select an entry in the Execution Stack Monitor; then, do the following: 

1 . Select one of the statements for that entry in the Statement Monitor. 

2. Select Confirm Reposition. 

The selected statement runs next. 

To start the test over from the beginning, select Restart Test from the Options 
menu. 

Changing parts dynamically 

When a test is suspended, you can modify parts before resuming the test. 
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You can make changes to parts using the VisualAge Generator editors. For the 
changes to take effect on parts being used by the test facility, from the File 
menu in the editor, you must select Save or Save As. 

At any time, you can resume the test from the point in the program where it 
was suspended. 

Once you have modified the part definitions and you want to resume testing, 
the changes you made might affect where you can resume the test. 

In general, changes to data (data items in records and tables and variable 
fields in maps) do not affect where the test can be resumed. However, 
changes to logic (statements in functions, flow statements associated with 
main functions, and programs) can cause the test facility to automatically reset 
the statement pointer to an earlier point than where the test was suspended. 

The following list explains when the test facility repositions the statement 
pointer after changes are made to a part: 

Programs 

The statement pointer is automatically repositioned to the beginning 
of the program. If the program is a called program, the statement 
pointer is repositioned to the CALL statement that called the changed 
program. 

Functions 

The statement pointer is automatically repositioned to the statement 
where the function is first referenced in the Execution Stack Monitor. 

Maps If the changed map is currently displayed, the statement pointer is 

automatically repositioned to the start of the CONVERSE I/O option. 
The presentation of the map might not change when this happens. 

Data items, records and tables 

Generally, no change in the position of the statement pointer is 
required; however, the test facility re-initializes the data values for the 
changed part. 

Suspending a test 

A test can be suspended by one of the following methods: 
• You select the Step button 




on the Test Monitor window 
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• You select the Stop button 



on the Test Monitor window 

• A breakpoint is encountered 

• A map is displayed as a result of a CONVERSE I/O option 

• An error occurs 

• The program ends 

Resource association files 

The test facility uses a resource association file to access the files used by the 
program being tested. Generally a system administrator creates a resource 
association file for all of the developers in an organization. The following 
graphic illustrates how the test facility uses resource association files. 
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Figure 18. Resource Association File usage 



Record definitions have file names, which are logical names in the resource 
association file. Each logical name is associated with a physical file. The file 
specifications in the resource association file hold the detailed characteristics 
for the physical file. 



You can define resource associations for three file organizations: serial, 
relative, and indexed files. If the file organization is indexed, the physical file 
contains the data records and the primary index. This physical file is called 
the primary file. 
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Alternate indexes are stored in other physical files called alternate index files. 
The alternate indexes are constructed on key fields in the data records that are 
usually distinct from the key field used to construct the primary index. You 
specify the offsets and lengths of the key fields when you provide the file 
specifications for the primary and alternate files. 

The following graphic illustrates the connections between alternate indexes 
and physical files: 
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Figure 19. Alternate Indexes and Primary Files 



When you use the Data File Conversion Utility to create indexed physical 
files, you do not have to use the utility to create the alternate files. If the 
alternate files do not exist when the first access is made to an alternate index, 
the alternate file for the index is built automatically. 



If you use the Data File Conversion Utility to create an alternate index file, 
only that single alternate index file is created, using the alternate index keys 
from existing records in the primary file. No other alternate files are built, 
unless you use the Data File Conversion Utility utility to explicitly create 
them. 
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Setting up resource association files 

To set up a resource association file: 

1 . Determine the set of record definitions and printer map destinations that 
require resource associations. 

2. On the VAGen Parts Browser or the Test Monitor window, from the Tools 
menu, select Resource Association File. 

Note: Creating a resource association file applies only to indexed, relative, 
and serial files, not to databases. 

3. On the Resource Association File window, do the following: 

a. To add a new resource association file to the list, select Add. On the 
Primary File Specification window, specify the logical file name and file 
specifications for the primary file, then select OK. 

b. To view and work with alternate indexes for an indexed file, select an 
indexed file entry in the list, then select Alternate Indexes. 

C. To save the resource associations in the resource association file, from 
the File menu, select Save or Save As. 

Setting up resource association files 

To set up a resource association file: 

1 . Determine the set of record definitions and printer map destinations that 
require resource associations. 

2. On the VAGen Parts Browser or the Test Monitor window, from the Tools 
menu, select Resource Association File. 

Note: Creating a resource association file applies only to indexed, relative, 
and serial files, not to databases. 

3. On the Resource Association File window, do the following: 

a. To add a new resource association file to the list, select Add. On the 
Primary File Specification window, specify the logical file name and file 
specifications for the primary file, then select OK. 

b. To view and work with alternate indexes for an indexed file, select an 
indexed file entry in the list, then select Alternate Indexes. 

c. To save the resource associations in the resource association file, from 
the File menu, select Save or Save As. 

Converting files for use in the test facility 

VisualAge Generator provides a data file conversion utility to convert data 
files that exist on host systems to a format that the test facility can use on the 
workstation. 

To convert data files: 
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1 . Transfer the file containing the test data from the host system to your 
workstation in binary format. 

Note: Code points in the file on the host system should not be translated 
during the file transfer operation. 

2. On the VAGen Parts Browser or the Test Monitor window, from the Tools 
menu, select Data File Conversion. 

Note: Converting data files applies only to indexed, relative, and serial 
files, not to databases. 

3. On the Data File Conversion window, specify the record name, source file, 
translation table name, and originating system, then select OK. 

The conversion table name is ELACNxxx, where xxx is the NLS environment 
identifier. 

Calling external programs 

The test facility requires that all external programs be installed and 
configured. This includes prerequisite programs such as DB2/2. The following 
tasks give you instructions for calling an external program from the test 
facility. 

• Using a standard call 

• Using an entry point in a dynamic link library (DLL) 

• Calling COBOL routines 

• Using an external call 

For a more detailed description of possible calls from the test facility, refer to 
the linkage table section of the VisualAge Generator Client/Server 
Communications Guide document. 

Using standard calls 

To issue a standard call, ensure that the external program: 

• Is an executable file (.EXE), a command file (.CMD), or a batch file (.BAT) 

• Exists in a directory listed in the PATH statement 

When the call is made, a new session opens and show any output. When the 
program ends, the session closes. 

Using an entry point in a dynamic link library (DLL) 

To issue a call as an entry point in a dynamic link library (DLL), ensure that 
the external program: 

1 . Contains no EBCDIC or environment characters, such as hard-coded or 
special hexadecimal characters or data fields that are in a host system data 
format. Binary fields must be in proper byte order for the environment. 

2. Has parameters that follow the C-calling conventions. 
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The C-calling conventions means that the parameters are pushed onto the 
system stack in reverse order. Therefore, to call a program in a language 
that uses the PASCAL-calling conventions (which does not place 
parameters in the stack in reverse order), either the program reverses its 
parameters or the test facility calling program must reverse the order of its 
arguments on the call. 

3. Is compiled and linked in a DLL. This DLL must be in the PATH in 
Windows, or LIBPATH in OS/2. 

Note: There is only one entry point per DLL for a COBOL program; 

however, other languages can have more than one entry point per 
DLL. 

4. Uses a linkage table that contains an entry for the program name and a 
DLL with its entry points. In the following example, the linkage table 
entries enable the programs namel and namex to be called as defined in 
the VisualAge Generator program. The dllname and entrypoint values 
specify the name of the DLL and the called program. 

: cal 1 1 i nk appl name=namel 

1 i brary=dl 1 name 

external name=entrypoi nt 

1 inktype=dynamic. 
: cal 1 1 i nk appl name=namex 

1 ibrary=dl 1 name 

external name=entrypoi nt 

1 inktype=dynamic. 

With the linkage table entries set as above and the linkage table part name 
specified on the VAGen - Test Linkage tab, the namel program can be 
called from the test facility. 

Parameters to an external program are passed by reference. That is, an 
address is passed to the external program of the storage area of the argument 
passed by the calling program. 

Calling COBOL routines 

If you are calling a COBOL routine, consider the following: 

• Parameters are passed as pointers in VisualAge Generator. 

• Define the COBOL routine as a SUBPROGRAM. 

• In the COBOL routine, set RETURN-CODE to 0 before a GOBACK. 

• Compile the COBOL routine with the LARGE or HUGE option so that the 
program uses FAR POINTERS. 

• Link the COBOL routine with a stack size of 32000. 
Using external calls 

To setup the test facility and your environment to use External Calls, on the 
VAGen - Test Linkage tab, specify a linkage table part name. 
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The CALL statement in VisualAge Generator language is interpreted by the 
test facility during the test according to the following rules: 

1 . If a linkage table entry exists for the program call, data is formatted and 
called as specified in the linkage table entry. 

2. If the named program cannot be found in the linkage table, the test facility 
searches for a .EXE, .CMD, or .BAT file to run. 

3. Control is returned to the test facility. 

Calls to local C and COBOL DLLs are performed using standard system calls. 
As with any called program, the user needs to ensure that the called program 
is expecting data in the proper format. 

All local calls to DLLs are performed by passing pointers on the stack using 
the standard C linkage format. 

Local called programs should have an explicit BITMODE declaration in their 
linkage table entries. If an explicit declaration does not exist, a 32-bit call is 
assumed. 

Local called programs should have their parent DLL declared. If a parent DLL 
is not declared, the test facility assigns a parent DLL whose name matches the 
program name. 

If a local called program returns a value, the test facility expects a value 
between 0 and 255. If a value is not returned, the test facility continues. 

Dependencies: All local called DLLs must expect to receive the pointer array 
on the stack. Therefore, all called programs should be 
compiled with, or written so that they can be called by, 
SYSLINK linkage type (standard C linkage). Without the 
SYSLINK linkage type, the call will not succeed. All local 
called DLLs must be located in the PATH in Windows, or 
LIBPATH in OS/2. 

Other considerations: All calls to C DLLs are case sensitive. However, 

VisualAge Generator only passes uppercase program 
names. Therefore, it is required that the name of any 
program called from the test facility be in uppercase. 
DLLs must be able to be called dynamically even if 
they are meant to be bound statically. 

Binding to a relational database 

If your program uses relational databases, you must bind to the database the 
program uses. In most cases, you need not explicitly bind VisualAge 
Generator to relational databases. If an access plan does not exist for 
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VisualAge Generator to use a database, VisualAge Generator can 
automatically run the SQLBIND command to create the access plan. You can 
select the desired SQL date/time format from the VAGen - SQL tab on the 
VisualAge Preferences window. This information will be used when VisualAge 
Generator runs the SQLBIND command. 

Note: To override any other options besides the date or time format, you can 
explicitly bind to the databases your program uses. Because VisualAge 
Generator acts on behalf of your program when requesting SQL 
services from DB2/2, you must use VisualAge Generator as the 
program object name when explicitly binding to the relational 
databases. The physical file name for the bind file for VisualAge 
Generator is HPTDB230.BND. 

For detailed information on running SQLBIND, refer to your DB2/2 
documentation. 

Using breakpoints 

Use breakpoints to suspend the test at specific locations or under specific 
conditions within a program. 

You can perform the following tasks with breakpoints. 

• Setting breakpoints 

• Removing breakpoints 

• Setting qualified breakpoints 

• Enabling and disabling breakpoints 

• Encountering breakpoints 

Setting breakpoints 

You can set breakpoints at any time from the VAGen Parts Browser, Test 
Monitor, or any VAGen Editor by doing the following: 

1 . From the Tools menu, select Set Testpoints. 

2. On the Set Testpoints window, you can set a breakpoint that applies to the 
entire part or to elements of the part using the 

Q] 

symbols to the left of the elements in the part. 

3. On the Set Testpoints window, the 




symbol shows that the breakpoint is an unqualified breakpoint. 
Elements that can have breakpoints 

You can set breakpoints on the following: 
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• Logic elements 

- Programs 

- Functions 

- Statements 

- Logic EZE words 

• Data elements 

- Data items in records 

- Data items in tables 

- Variable fields in maps 

- Data EZE words 

Note: Breakpoints on data items and variable fields can be set only by using 
the Set Testpoints window for the parts in which they are contained. 

Removing breakpoints 

Breakpoints remain set until you remove them. Breakpoints remain set even 
when a part is modified. 

A special case applies when breakpoints are set on statements. If you set a 
breakpoint on statement 100, delete statement 100, and save the part, then 
there is no longer a breakpoint set for statement 100. However, if you have a 
breakpoint set on the first statement in a function and you delete that 
statement and save the part, the breakpoint remains set on the first statement 
in that function. 

To remove breakpoints, you can do one of the following: 

• Remove a breakpoint individually, the same way you set the breakpoint. 

• Remove all breakpoints from the part you have open by doing the 
following: 

1 . On the Set Testpoints window, select Clear All Breakpoints. 

• Remove all breakpoints on all parts by doing the following: 

1 . On the Test Monitor window, from the Tools menu, select Remove 
Testpoints 




Remove All Breakpoints. 
Setting qualified breakpoints 

You can set a qualified breakpoint by double-clicking on the 
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symbol or the 



m 

symbol on the Set Testpoints window. 

A qualified breakpoint enables you to tailor the breakpoint to suspend a test 
when certain conditions are satisfied. On the Qualified Breakpoint window, do 
any combination of the following: 

1 . Specify a count range, using the Break On Encounter and Continue 
Through Encounter fields. 

2. Specify a condition, using the IF Condition field. 

If an encounter value and conditional value are both specified, both must be 
true for the break to occur. 

On the Set Testpoints window, the 

m 

symbol shows that the breakpoint is a qualified breakpoint. 
Enabling and disabling breakpoints 

You can disable breakpoints without actually removing them. Disabling all the 
breakpoints is useful when you want to control the test from the Test Monitor 
window. 

To disable breakpoints, do the following: 

1 . On the Test Monitor window, from the Options menu select Disable 
Breakpoints. 

2. To enable the disabled breakpoints, select Disable Breakpoints again. 
The 

symbol appears to the right of the Disable Breakpoints menu choice when 
the breakpoints are disabled. If the 

symbol is not present, the breakpoints are enabled. 
Encountering breakpoints 

The test is suspended when one of the following occurs: 

• An unqualified breakpoint is encountered 

• A qualified breakpoint whose qualifications have been met is encountered 
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The Test Monitor window shows the context of the test when the test is 
suspended. The following list describes the point at which the test is 
suspended for the kinds of breakpoints you can set: 

Logic elements 

The test is suspended before the element has run. The statement that is about 
to run is highlighted. 

Statement The test is suspended before the statement runs. 

Program The test is suspended immediately before control transfers to 

the program using a CALL, XFER, or DXFR statement. The 
CALL, XFER, or DXFR statement is highlighted and can be 
bypassed. 

Function The test is suspended immediately before control transfers to 

the function. The statement starting the function is highlighted 
and can be bypassed. When a function is used as an error 
routine for an 1/ O function, the I/O operation has already 
performed, but the error routine has not been started. 

Logic EZE word 

The test is suspended immediately before control transfers to 
the service provided by the logic EZE word. When the logic 
EZE word is used as an error routine for an I/O function, the 
I/O operation has already occurred. 

Data elements 

The test is suspended after the contents of the element have been modified. 
The statement that caused the element to be modified is highlighted. 

Data EZE word 

The test is suspended after the contents of the data EZE word have 
been modified. 

Data item or variable field 

The test is suspended after the contents of the data item or variable 
field have been modified. 

Using tracepoints 

Use tracepoints to control the collection of trace information during a test. The 
trace entries collected provide a historical record of the occurrences during the 
test. If you require the same output from several tests, then set tracepoints 
rather than breakpoints. 

A tracepoint determines whether tracing is on or off when entering and 
exiting the part. Tracepoints take effect whenever a test is rim. 
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The following tasks give you instructions for using tracepoints. 

• Setting tracepoints 

• Removing tracepoints 

• Setting qualified tracepoints 

• Enabling and disabling tracepoints 

• Viewing trace entries 

Setting tracepoints 

You can set tracepoints at any time from the following windows: 

• Any editor window 

• VAGen Parts Browser 

• Test Monitor 

by doing the following: 

1 . From the Tools menu, select Set Testpoints. 

2. On the Set Testpoints window, select the 




symbol next to the part. 
3. On the Set Testpoints window, the 




symbol shows that the tracepoint is an unqualified tracepoint. 
Elements that can have tracepoints 

You can set a tracepoint on the following: 

• Programs 

• Functions 

Removing tracepoints 

Tracepoints remain set until you remove them or you close the Test Monitor 
window. 

To remove tracepoints, you can do one of the following: 

• Remove a tracepoint individually, the same way you set the tracepoint. 

• Remove all tracepoints on all parts by doing the following: 

1 . On the Test Monitor window, from the Tools menu, select Remove 
Testpoints 




Remove All Tracepoints. 
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Setting qualified tracepoints 

You can set a qualified tracepoint by double-clicking on the 

Q 

symbol or the 

symbol on the Set Testpoints window. 

A qualified tracepoint turns tracing on or off upon entering and exiting the 
part containing the tracepoint when certain conditions are satisfied. On the 
Qualified Tracepoint window, do the following: 

1 . Specify a count range, using the Begin On Encounter and Continue 
Through Encounter fields. 

2. Specify a condition, using the IF Condition field. 

If an encounter value and a conditional value are both specified, both must be 
true for the trace to occur. 

On the Set Testpoints window, the 




symbol shows that the tracepoint is a qualified tracepoint. 
Enabling and disabling tracepoints 

You can control how trace entries are collected without affecting tracepoints, 
by setting trace filters to collect different amounts of trace information. By 
specifying certain trace filters you are only specifying what is displayed in the 
Trace Monitor window, not what has actually been traced. If tracing is turned 
on, all possible trace entries are collected. However, the trace entries displayed 
in the Trace Monitor window are determined by the trace filters you set. 

To control how trace entries are collected during a test, on the Test Monitor 
window from the Tools menu, select Trace and one of the following: 

• Select Trace All to trace everything possible, ignoring all tracepoints. 

• Select Tracepoints Only to turn tracing on or off according to the 
tracepoints you have set. Tracing is off when the test starts. 

• Select Trace Nothing to trace nothing and ignore all tracepoints. 
Viewing trace entries 

You can view and work with the collected trace entries on the Trace Monitor 
window. You can open as many Trace Monitor windows as you need. 
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A statement trace entry contains the text of the statement that runs when 
tracing is enabled. Other types of trace entries are created depending on the 
nature of the operation taking place. Sequence numbers that show the order 
in which the trace entries were collected are provided in the Trace Monitor 
window. 

To open and work with the trace entries in a Trace Monitor window, do the 
following: 

1 . On the Test Monitor window, from the Trace menu, select View Trace. 

2. If you open another Trace Monitor window, from the Options menu, select 
Set Filters to set the filters that determine what types of trace entries are 
displayed. 

3. If you want to refresh the entries that appear in the Trace Monitor window 
after selecting a new set of trace entry filters, from the Options menu 
select Refresh. 

Using watchpoints 

Use watchpoints to view the contents of selected data items, variable fields on 
maps, and data EZE words as a test progresses. Any changes to the displayed 
content of these elements are updated automatically. 

The following tasks give you instructions for using watchpoints. 

• Setting watchpoints 

• Removing watchpoints 

• Viewing the data 

• Modifying the contents of data items 
Setting watchpoints 

You can set watchpoints at any time from the following windows: 

• Any editor 

• Test Monitor 

• VAGen Parts Browser 

by doing the following: 

1 . From the Tools menu, select Set Testpoints. 

2. On the Set Testpoints window, select the 

□ 

symbols to the left of the data items or variable fields within the part. 
The 
■ 

symbol shows that a watchpoint is set. 
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Elements that can have watchpoints 



You can set watchpoints on the following elements: 

• Variable fields in maps 

• Data items in records 

• Data items in tables 

• Data EZE words 

Removing watchpoints 

Watchpoints remain set until you remove. 

To remove watchpoints, you can do one of the following: 

• Remove a watchpoint individually, the same way you set the watchpoint. 

• Remove all watchpoints from the part you have open by doing the 
following: it 

1 . On the Set Testpoints window, select Clear All Watchpoints. 

• Remove all watchpoints on all parts by doing the following: 

1 . On the Test Monitor window, from the Tools menu, select Remove 
Testpoints 




Remove All Watchpoints. 

Note: Removing all watchpoints from a part or from all parts enables you to 
start fresh at setting watchpoints. 

Viewing the data 

Only watchpoints set on data elements, such as data items, variable fields on 
maps, and data EZE words in the current program, are monitored. The 
Watchpoint Monitor on the Test Monitor window displays the names of the 
data elements' watchpoints that are set on and their contents. Any changes to 
the content are updated dynamically, including when the substructure or 
superstructure of the data item changes or when a data item in a redefined 
record changes. 

When a new program begins running, the contents of the Watchpoint 
Monitor changes to contain the data elements that watchpoints are set in that 
program. If no watchpoints are set in the new program, the Watchpoint 
Monitor is cleared. 

Modifying the contents of data items 

You can modify the contents of the data items in the Watchpoint Monitor by 
double-clicking on the item. 
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Data items that are not displayed in the Watchpoint Monitor can be modified 
using the Data Item Editor. 

Testing Web Transaction programs 

You can test a Web Transaction program independently through ITF: 

1 . Select the Web Transaction program you want to test. 

2. Select the Test action. 

When you test a Web Transaction program that CONVERSES a UI Record, 
ITF generates a default HTML page with all the data in the UI Record. ITF 
invokes the web browser that is registered to your operating system and 
sends the generated HTML page to the browser. 

3. Press a submit button on the generated HTML page. 

When you submit the form back to ITF, all the edits defined in the UI 
Record are run. If any of the edits fail, the page is resent to the browser 
with error messages under each field that failed its edits. If the edits 
succeed, all data is returned to ITF and the program continues on after the 
CONVERSE. At this point you can check the defined Submit Value Item in 
the UI Record for the value of the actual Submit button you pressed. 

4. Compare the UI record definition to the generated HTML page. 

At this point you can check the defined Submit Value Item in the UI 
Record for the value of the actual Submit button you pressed. 

5. View the default Entrypoint Page at the conclusion of the program. 

When the program terminates, ITF sends a default Entrypoint Page to the 
browser. The page shows all Web Transaction programs currently loaded 
in the development workspace/image that are available for testing. ITF 
simulates what occurs at run time when a program terminates by sending 
a default Entrypoint Page to the browser. During run time, the 
GatewayServlet serves the defined Entrypoint Page when a program 
terminates. 

Testing considerations for VAGen scripts 

Using VAGen scripts allows the synchronous execution of Java/Smalltalk 
scripts from within VAGen functions that are invoked by GUI clients. When 
an EZESCRPT statement is encountered in a VAGen GUI client function, test 
facility makes a "call" to a Java/Smalltalk script. Scripts that can be invoked 
this way are public instance methods (not static methods) or instance methods 
that accept no parameters and are stored on the GUI client class. Any client 
data modifications that have been made are signaled at this point and then 
the script is executed. 

Either the signalling of data modifications or the script itself can cause other 
VAGen functions or programs to execute. It is now possible for the system to 
begin execution of a VAGen event while in the middle of executing another 
VAGen event. The new event is processed and then control returns to the GUI 
client to continue either the data modifications or script execution. When the 
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GUI client has completed execution of the script, control returns to the 
original function that contained the EZESCRPT statement. 

There are several important differences you will notice in the behavior of the 
VisualAge Generator Test Monitor when you use it to test client code that 
uses VAGen scripts: 

• When EZESCRPT statements trigger other VisualAge Generator logic 
events, the same Test Monitor window is displayed and the subsequent 
VAGen functions or programs are shown in the Execution Stack Monitor. 
When you use the Execution Stack Monitor to view the history of VAGen 
logic execution, you can see the original function that contained the 
EZESCRPT statement that is in the middle of processing. This behavior is 
very similar to the way function or CALL statements are handled. The 
identifier, '(from script)' is displayed at the end of the Execution Stack 
monitor entry, to show which logic events were triggered indirectly by an 
EZESCRPT statement. 

• Shutting down the Test Monitor while you are testing a VAGen logic event 
triggered by an EZESCRPT statement will not affect the GUI client being 
tested. That particular logic event is canceled, but control is returned to the 
GUI client to continue script processing. If the GUI client invokes another 
VisualAge Generator logic event, then a new Test Monitor will open and 
run the requested logic. You must shutdown the GUI client to quit the test. 

• If the Smalltalk script called by the EZESCRPT statement has an error, test 
facility does not attempt to mask the error. Instead, the VisualAge Smalltalk 
debugger window opens with the error displayed. You can fix the script 
error and select Resume to continue the test. Control will return to the Test 
Monitor when the GUI client script is finished executing. If you close the 
debugger without resuming, the Test Monitor will be left up but will be 
unusable. You can shut down the Test Monitor yourself or it will be closed 
at a later time. If other VisualAge Generator logic events are invoked, a 
new Test Monitor will be opened. 

• If the Java script called by the EZESCRPT statement has an error, test 
facility does not attempt to mask the error. Instead, the exception will be 
caught and handled in the normal test facility manner. The Test Monitor 
will be left up, but will be unusable. You should use the VisualAge for Java 
debugger to terminate the GUI client, which will shut down the Test 
Monitor. After fixing the script error, you can restart the GUI client test. 

• If you reposition the test, or save a VisualAge Generator part that causes 
the test facility to reposition the test, while you are executing an EZESCRPT 
statement or executing logic events triggered by an EZESCRPT statement, 
the Java/Smalltalk script is canceled and no other script statements are 
executed. This means that any other VisualAge Generator logic events are 
not invoked. If the test was repositioned prior to the EZESCRPT statement, 
you can continue testing to execute the statement again and completely test 
the script. 
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Testing server programs 

You can use the VisualAge Generator test facility to test server programs 
running locally or on remote systems. To test a server program you must have 
a GUI client that accesses the server program and the server program must be 
loaded into the workspace/image. 

To test a server program: 

1 . Use the VisualAge Composition Editor to build a graphical user interface 
that accesses the server you want to test. 

2. Add the following statements to your linkage table: 

appl name=program name 

1 inktype=remote or 1 i nktype=csocal 1 

remoteapptype=i tf 

remotecomtype=tcpip, ipc, direct, etc. 

Note: Any remotecomtype that is appropriate for the client and the server 
can be used with remoteapptype=i tf. 

3. Test your user interface. When the client calls the server, the Called Server 
Test Monitor window is displayed on the system where the server is 
running. 

4. On the prompt window, select OK to start testing the server program. 



Dynamic Program Partitioning 

Developing distributed program systems can be complex. The individual 
programs of a distributed system must be placed onto the client/ server 
machines before the system can be run. This process is known as 
"partitioning" the program system. Placing too much of a system's logic on 
the client side can result in poor performance. Ideally, distributed program 
systems are partitioned to minimize communications between machines, 
which helps to achieve optimal performance. 

Dynamic Program Partitioning is a feature added to the VisualAge Generator 
test facility to assist in determining how to appropriately partition distributed 
program systems for good performance. This feature supports automatic 
default placement of GUI client, map, and database programs on machines. 
The program system can be configured dynamically during a test run, with a 
focus on communications between machines and the system constraints. The 
Dynamic Program Partitioning feature will highlight situations where changes 
are needed in the application system structure to achieve better performance. 

The Dynamic Program Partitioning feature provides a visual display of the 
interactions between programs while the application system is being tested. 
Each program is displayed as a floating icon. Programs that communicate 
extensively with each other and / or transfer a large amount of data will 
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"cluster" together - that is, they will move toward one another on the display. 
This visual display is called a Clustering View. 

To take advantage of Dynamic Program Partitioning, logic should be broken 
out into separate programs. These new programs should contain no I/O. They 
will be free to "float" to the target machine where most of their interactions 
take place. This will usually result in optimal partitioning. 

Creating and using icons in the Clustering View 

The first time a call is made from one program to another, a program icon for 
each program appears in the Clustering View window. Programs that 
communicate extensively with each other or transfer a large amount of data 
will "cluster" together - that is, they will move toward one another in the 
Clustering View window. 

Note: In order to enable Dynamic Program Partitioning prior to a call from a 
client to a VisualAge Generator program, either set a breakpoint on the 
program part or select Break on Event Entry from the Test Monitor. 
Once the break is encountered, open a Clustering View window. This 
enables Dynamic Program Partitioning before the call actually occurs so 
an icon for both the client (a non- VisualAge Generator part) and the 
VisualAge Generator program appear in the Clustering View window. 

Enabling Default partitioning from the Partitioning Setup window results in 
client, map, and database programs being placed on the appropriate target 
machines. The program system can be dynamically configured during a test, 
with focus on communications between machines, and the system constraints. 
Using the Clustering View window, situations are identified where changes 
are needed in the program system structure in order to achieve better 
performance. 

During default partitioning, target machine icons are created as needed. 

With default partitioning, map programs are automatically placed on a client 
machine icon. Database programs are automatically placed on a database 
server machine icon. Logic programs can be manually placed when they are 
called or they can be enabled to float, and then the logic programs can be 
placed after testing is complete. 

The icon representing a program identifies its type: Map, Database, or Logic 
(programs which do not contain any I/O operations). Below each icon is a 
colored label giving the name of the program. The color of the label indicates 
the number of calls received by the program. The color can range from blue 
(or "cold"), indicating few calls, to red (or "hot"), indicating many calls. The 
full spectrum of colors is shown permanently at the bottom of the Clustering 
View window for reference. 
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A line is drawn between each interacting pair of programs. Think of the line 
as a spring trying to pull two programs together. The more two programs 
interact, the harder the spring tries to pull them together. The color of a line 
indicates how hard it is trying to pull the two programs together. The color 
can range from blue, indicating little pull on the programs, to red, indicating a 
strong pull. Blue lines indicate programs that are suitably positioned relative 
to the other programs, considering the amount they have interacted. Red lines 
indicate programs that are too far apart, considering the amount they have 
interacted. 

As the test runs, the system tries to reach a stable configuration. Programs 
with a strong pull (as indicated by a red line between them) tend to move 
toward one another. The line changes to a "cooler" color (that is, toward blue 
on the color spectrum) as the programs move and the amount of pull 
decreases. 

Multiple Clustering View windows can be active simultaneously. This enables 
the placing of programs in different configurations to observe system 
behavior. To add a Clustering View window, select View Clustering from the 
Partition option on the Tools menu on the Test Monitor. 

The position at which programs finally settle relative to one another provides 
guidance concerning the machines on which the programs should be placed 
in a client /server or n-tier architecture (in order to achieve the best 
performance, given the system constraints). 

Using saved topology information 

Topology information includes details about each target machine name, 
environment, position, and so forth. When rerunning a test that has the same 
target machine configuration, you can open the clustering view based on the 
saved topology to avoid having to manually create the target machines. 

Controlling the test 

To observe the program system clustering behavior, initiate the test of the 
program from the test facility. The first time a call is made from one program 
to another, a program icon for each program appears in the Clustering View 
window. During the test, lines are drawn between programs, and programs 
will float into position around the Clustering View window. 

The test can be stopped at any point from the test facility. 

Working with programs and target machines 

Target machine icons can be added and positioned manually to define the 
distributed system. Target machine icons have an associated name, type, and 
target environment. A target machine icon can be added from the Clustering 
View menu bar by selecting Add New Target Machine from the Options 
menu. 
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A program icon can be placed on a target machine icon. To place a program, 
do the following steps: 

• Select a target machine icon and program icon(s). 

• Click the right mouse button to display the program context menu 

• Select Place Programs 

Placing a program icon on a target machine icon causes the program to run 
on the selected target machine during the actual run of the generated code on 
the distributed system. In the Clustering View window, the icon for the placed 
program will be attached to the selected target machine icon. Other programs 
will float toward or away from the placed program, but the placed program 
remains with its target machine. The pull between programs can then be 
observed. For example, a test can be run with all of the client programs 
placed on a client target machine, and all of the server programs placed on a 
server target machine. If any of the lines between the client programs and 
server programs are red at the end of the test, this indicates a performance 
problem. 

When the programs in the distributed system appear to be placed 
appropriately, code generation can be performed for any selected program 
within a Clustering View window. 

After code for all programs has been generated, the system can be run on the 
target configuration. 

Selecting target machines and programs 

Individual target machines and programs can be selected as follows: 

• Place the cursor over the icon label 

• Click the left mouse button 

A black frame appears around the label of an icon that has been selected. 
To select more than one icon, do the following: 

• Press and hold the Ctrl key when the cursor is over the desired icon's label 

• Click the left mouse button 

A group of icons can be selected by surrounding them with a bounding box, 
as follows: 

• Place the cursor near the group of icons to be selected 

• Press and hold the left mouse button, and move the cursor 

A bounding box is formed that will follow the cursor. All icons within the box 
are selected when the left mouse button is released. 
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You can deselect the icons as follows: 

• Move the cursor to a position in the Clustering View window where there 
is no icon 

• Click the left mouse button 



Using the VisualAge for Java debugger 

The Java debugger in VisualAge Generator Developer is used mainly in 
conjunction with the Interactive Test Facility (ITF) to test graphical user 
interfaces (GUIs) and object-oriented scripts. 

If the Java script called by the EZESCRPT statement has an error, the ITF does 
not attempt to mask the error. Instead, the exception is caught and handled by 
VisualAge for Java. The Test Montior continues to run but is unusable at that 
time. If you can easily identify the error, you can fix the script error in the 
debugger, save the method and resume the test. If you cannot easily identify 
the problem, you should use the VisualAge for Java debugger to terminate the 
GUI client. This termination shuts down the Test Monitor. After you 
determine the cause of the error and fix it, you can restart the GUI client test. 

To set the exceptions that invoke the debugger, navigate as follows from the 
menu bar in the Workbench window: Window * Debug ■* Caught Exceptions 

For more information about the VisualAge for Java debugger, go to the 
Debugger window and press the Fl key for help. To get to the Debugger 
window, you can navigate as follows from the menu bar of the Workbench 
window: Window * Debug * Debugger 

Accessing VSAM files from the ITF and C++ generated programs 

This section explains how to convert data for accessing OS/390 VSAM files 
from ITF and from programs generated from C++ source code. 

VisualAge Generator provides automatic ASCII-to-EBCDIC and 
EBCDIC-to- ASCII conversion for host VSAM files. VSAM files on the host 
systems are typically stored as EBCDIC characters, although you can store 
ASCII data in them as well. VSAM files on the workstation are stored as 
ASCII characters. If you use the host system just for data storage, you do not 
need to convert the data to EBCDIC. However, if you want to access the data 
from programs on your workstation and from programs on the host system, 
you need to convert the data. 

In the VisualAge Generator Options page of the VAGen Parts Browser, you 
can specify whether you want the data converted and what conversion table 
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to use. Then the conversion happens automatically when you access OS/390 
VSAM files from ITF and C++ generated programs. 

Setup required to access remote VSAM files on OS/390 

For more detailed information on software prerequisites, setup instructions, 
and further details on accessing VSAM files using ITF and C++ generated 
programs, see the user's guide for the distributed file manager in SMARTdata 
UTILITIES for Windows. 

After installing the required products, configuring APPC, and verifying that 
you can establish an APPC session with your OS / 390 host, you are ready to 
configure DFM on the workstation. Following are the setup instructions: 

1 . Locate the file VSAMOS2.zip or VSAMNT.zip in the VisualAge Generator 
installation directory: msfaZZflh'on_dzrecfori/\programs\samples\ 

2. Unzip the file VSAMOS2.zip or VSAMNT.zip using the following 
command: 

PKUNZIP2 -d vsamos2.zip X:\VGDFM or PKUNZIP2 -d vsamnt.zip X:\VGDFM 

where X is a drive with at least 6 MB of free space. 

3. Follow the instructions in the install. readme file in X:\VGDFM directory. 

Note: If you have the SMARTdata UTILITIES component and Samples 

component of VisualAge installed, you do not need to unzip these zip 
files. You can use the DFM configuration files under IBM COBOL's 
samples\sdu or samples \hostdata directory. 

Accessing VSAM files from ITF 

To specify that you want to use VSAM files, do the following: 

1 . Select Open VAGen Parts Browser in the Workspace menu on the 
Workbench window. 

2. Select Options in the Window menu on the VAGen Parts Browser 

window, and the VisualAge Generator Options window displays. 

3. Select Test. 

4. At the bottom of the page, select either the Local VSAM or Remote 
VSAM radio button and click OK. 

5. Specify the VSAM translation file name if you want the ASCII-EBCDIC 
conversion done automatically. The default conversion table used is 
ELACNENU. If you don not want automatic data conversion, leave the 
VSAM translation file name empty. 

This will cause ITF to use VSAM files for all file accesses (on Windows NT, 
there is only remote VSAM file support). If you have changed your 
preferences to use Remote VSAM and you do not have the communications 
software setup and working, you will receive an error. 
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In addition to changing your preferences, you also need to specify the 
physical name and path in the ITF Resource Association File editor as follows: 

1 . In the Physical name field, specify the file name as it is on your OS/ 390 
system but without the high level qualifier. If the file does not already 
exist on your OS/390 system, Visual Age Generator will create it for you. 

2. On OS/2, in the Path field, specify the DFM drive letter, a colon, and the 
high level qualifier specified in the DFM configuration file (config.dfm). 

3. On Windows NT, in the Path field, specify the machine name or a shortcut 
name using the Universal Naming Convention. 

Accessing VSAM files from C++ generated programs 

Access to VSAM files from a C++ generated program is determined by the 
resource association file (RSC). Specify / FILETYPE= VSAM in the ASSOCIATE 
entry for a VSAM file. Because there is no local VSAM support on Windows 
NT, all VSAM file access is remote. If you do not have the communications 
software setup and working, you will get an error. 

To access a remote VSAM file on OS/2, preface the file name with the DFM 
drive letter. On Windows NT, specify the file name using the Universal 
Naming Convention. For more information on using VSAM and resource 
association files, see the VisualAge Generator Server Guide for Workstation 
Platforms. 

Known limitations 

• At present, OS/390 VSAM files are the only VSAM files that ITF can access 
remotely. 

• When issuing a SET record SCAN with a key value of x'FFFF' or a key 
value greater than the highest record in the file, the behavior of a 
subsequent SCANBACK differs between local and remote VSAM. If 
accessing local VSAM, an I/O error will be returned instead of the last 
record. If accessing remote VSAM, the last record in the file will be 
returned. 

• Serial VSAM file "Scan" operation needs Access Mode to be set to "READ" 
only. So if you specify "READ/ WRITE" in the resource association file and 
performs "Scan" operation, you will have a hard error return code. The 
implication is that you cannot combine serial VSAM "Scan" operation 
together with other operations require "READ/WRITE" Access Mode for 
serial VSAM file access. You will have to separate these operations out and 
change the Access Mode accordingly in the resource association file for 
serial VSAM file. 
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Accessing DL/I from ITF with VisualAge middleware 

Accessing DL/I from ITF with VisualAge middleware includes the following 
steps: 

• Installing the remote DL/I component on the workstation. 

• Setting up the VisualAge remote DL/I component on the workstation and 
MVS. 

• Selecting VisualAge as the DL/I-related middleware. 

• Optionally, checking the setup status and changing the login for VisualAge 
remote DL/I. 

• Optionally, setting up tracing for the VisualAge remote DL/I component. 

• Optionally, changing the IMS batch job from the workstation. 

Installing the remote DL/I component on the workstation 

During installation, the VisualAge remote DL/I component is not installed by 
default; you need to select a custom setup. Guidance is provided by 
instructions on the install screens. 

For details on installation, see the VisualAge Generator Installation Guide. 
Setting up the VisualAge remote DL/I component 

Changes are necessary on both the workstation and MVS to support the 
VisualAge remote DL/I component. For details, see the following web site: 
http://gwareview.software.ibm.com/software/ad/vi sgen/1 i brary/dl i setup.html 

Selecting VisualAge as the DL/l-related middleware 

To select VisualAge as the DL/I-related middleware for test time: 

1 . From the VAGen Parts Browser menu bar, click Windows^Options. 

2. The VisualAge Generator Options screen appears. 

3. In the left pane, click DL/I. 

4. In the right pane, under Database Access Middleware, select one of the 
following: 

• Micro Focus Mainframe Express 

• VisualAge 

If you select VisualAge, a built-in facility (if installed) provides DL/I access 
remotely on MVS, where VisualAge brings up an IMS batch environment. 

With the VisualAge option, you can access DL/I in ITF from either Windows 
NT or OS/2, even if your organization lacks an IMS Transaction Manager on 
MVS. The VisualAge option does not support a local DL/I simulation and 
does not access IMS Fast Path databases. 
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For details on the other DL/I-related selections on the Visual Age Generator 
Options screen, see the VisualAge Generator Design Guide chapter on 
developing DL/I programs. 

Checking the setup status and changing the login for VisualAge remote 
DL/I 

If you are using the VisualAge option for remote DL/I access, you can learn 
the status of a workstation-to-MVS connection or can change the MVS login 
by invoking one of the following utilities: 

• DLICHECK verifies that the connection is working. 

1 . Go to an operating system command prompt. 

2. Type DLICHECK and press ENTER. 

3. If you have not entered a user ID and password either in ITF or by a 
previous use of one of the utilities, a dialog box is displayed; type a 
user ID and password and press ENTER. 

4. If a workstation-to-MVS connection is effect, message IWZ370I is 
displayed. Although messages are displayed if the connection fails, you 
may wish to use additional sources to help diagnose the problem: 

- Use the IBM Personal Communications APING utility to ensure that 
communications with the host have been established. 

- Review the MVS log. 

- Perform a full IBM Personal Communications trace on CPIC-APPC 
and Token Ring communications, and in particular review the 
messages returned from MVS. 

• DLICHKP verifies that the connection is working and that a specific PSB 
can be scheduled and terminated. To invoke that utility: 

1 . Go to an operating system command prompt. 

2. Type DLICHKP and, without quote marks, the name of the PSB on 
MVS, then press ENTER. 

3. If you have not entered a user ID and password either in ITF or by a 
previous use of one of the utilities, a dialog box is displayed; type a 
user ID and password and press ENTER. 

4. If a workstation-to-MVS connection is effect, message IWZ370I is 
displayed. Although messages are displayed if the connection fails, you 
may wish to use additional sources to help diagnose the problem: 

- Use the IBM Personal Communications APING utility to ensure that 
communications with the host have been established. 

- Review the MVS log. 

- Perform a full IBM Personal Communications trace on CPIC-APPC 
and Token Ring communications, and in particular reviewthe 
messages returned from MVS. 



138 VisualAge Generator: User's Guide 



• DLILOGIN changes the user ID and password used when your workstation 
next connects to the remote MVS system. You specify a user ID and 
password when invoking ITF, but DLILOGIN is necessary to specify a 
different user ID and password after you start working in ITF. To invoke 
that utility: 

1 . Go to an operating system command prompt. 

2. Type DLILOGIN and press ENTER. 

3. A dialog box is displayed; you type a user ID and password and press 
ENTER. 

4. No messages are displayed to indicate success or failure (the login data 
is stored in a local cache), but you can use ITF or invoke DLICHECK or 
DLICHKP to determine whether the connection is working. 

Tracing remote DL/I calls 

If you are using option VisualAge for remote DL/I access, use environment 
variables DLITROPT and DLITROUT to trace remote DL/I calls. 

The process for specifying an environment variable depends on your 
operating system. 

• On Windows NT: 

1 . Click Start->Settings->Control Panel->System->Environment 

2. Click on an entry in the System Variables section of the screen (to set 
variables for every user of the workstation) or in the User Variables 
section (to set variables only for the current user of the workstation). 

3. For each variable you wish to set, do the following: 

a. In the Variable textbox, type the name of the variable. 

b. In the Value textbox, type the setting. 

c. Click Set. 

4. To put the variables into effect and continue working on the screen, 
click Apply. To put the variables into effect and close the screen, click 
OK. 

• On OS/2: 

1 . Use a text editor to open the file config.sys, which is in the root 
directory of the drive in which OS/2 is installed. 

2. Add an entry of the following form: 
set variable_name=variable_value 

3. Reboot the machine. 

The environment variables for tracing DL/I calls are as follows: 

• DLITROPT specifies DL/I tracing options and can take either of two values: 
- 0, which indicates that only information on DL/I errors is retained in a 

file identified in environment variable DLITROUT. 
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- 1, which indicates that information on all DL/I activity is retained in that 
file. 

The default setting of DLITROPT is 0. 

• DLITROUT specifies the file that receives DL/I trace information. If the 
value is blank or the environment variable DLITROUT is not present, 
VisualAge writes trace information to file VAGRMDLI.OUT 

If you do a typical install of VisualAge for Java, the file is in directory 
C:\IBMJava\rmtDli; the equivalent directory for VisualAge Smalltalk is 
C:\Program Files \ VAST \rmtDli (on Windows NT) and C:\VAST\rmtDli 
(on OS/2). 

The following environment variables also support the VisualAge option for 
remote DL/I: 

• RMTDLI_PARTNER_LU specifies the name of the partner LU alias and is 
set during communications setup. 

• RMTDLI_PARTNER_TP specifies the TP name of the remote DL/I server 
and is set during communications setup. 

• RMTDLI_SERVER_ENV specifies the fully qualified name of the Server 
Environment File, which is described in the next section. Do not delimit the 
file name with quote marks. 

Changing the IMS Batch Job from the Workstation 

If you are using the VisualAge option for remote DL/I access, the following is 
true: When the test facility does its first DL/I call, the JCL in a TP profile 
starts an IMS batch environment, and that environment remains in effect until 
the user brings down the test facility. 

You can rely on the JCL in a TP profile, but you can modify it by use of the 
Server Environment File, which resides on the workstation. Invoking utility 
DLICHECK or DLICHKP also starts the IMS batch environment, and 
modifications specified in the Server Environment File are also in effect. 

Within a Server Environment File, you specify DD names, along with the 
associated dataset names that you want the Remote DL/I server to allocate 
dynamically before bringing up the IMS batch environment. If a DD name 
you specify is already in the JCL, the DD statement is an override; otherwise, 
the new DD statement is an addition. 

The syntax for specifying a DD name and an associated data set name in the 
Server Environment file is as follows: 
DD=ddname DSN=data_set_name 

Several rules apply: 

• Both the DD name and the data set name must be on the same line. 
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• The data set is allocated dynamically with DISP=SHR. 

• Concatenation is supported only when the DD name is IMS. If more than 
one library is required for the IMS DD, use one line per data set. 

• The only supported DD statement parameter is DSN. 

• The only valid DSN value is a data set name. The Server Environment File 
supports neither DD DUMMY nor SYSOUT. 

An example of the Server Environment File is as follows: 

DD=RDLIDSN DSN= IMS . DATABASE. RDLI DSN 
DD=RDLIDSNO DSN= IMS. DATABASE. RDLI DSNO 
DD=IMS DSN=MYTEST. PSBLIB 
DD=IMS DSN=IMS. PSBLIB 
DD=IMS DSN=IMS.DBDLIB 

The test facility gets the fully qualified name of the Server Environment File 
from the environment variable RMTDLI_SERVER_ENV. If the environment 
variable is missing or refers to a blank or non-existent Server Environment 
file, the JCL in the TP profile is used as is. 

Note: The job that starts the IMS batch environment on MVS ends when you 
re-invoke utility DLICHECK or DLICHKP or when you close the test 
facility. 

In relation to DLICHECK or DLICHKP, changes to the Server 
Environment File go into effect with the next invocation of the utility. 
In relation to the test facility, however, changes to the Server 
Environment File go into effect only after you have closed and restarted 
VisualAge. As a result, you can change the Server Environment File, 
invoke DLICHKP, determine that a PSB is scheduled correctly, then 
re-enter the test facility and find that the PSB can not be scheduled 
because an older Server Environment File is in effect. To end such a 
discrepancy, close and restart VisualAge. 



Chapter 5. Testing VAGen parts 141 



142 VisualAge Generator: User's Guide 



Chapter 6. Generating VAGen parts 



This chapter describes how to generate VAGen parts by using VisualAge 
Generator Developer on Java. 



Setting generation options 

For VisualAge Generator Developer on Java, there are two kinds of 
"generation options" you can set. You can specify default preferences for 
generation on the VisualAge Generator Options page and you can also set 
specific generation options on the Generate window or by creating a 
Generation Options part. 

To set default generation preferences: 

1 . From the Workbench, select Workspace^Open VAGen Parts Browser. 

2. From the VAGen Parts Browser, select Window->Options 

3. On the VisualAge Generator Options navigation pane, select Generation. 

4. For code generated for the client, in the Client group box, select a 
generation options part. 

5. For code generated for the server, in the Server group box, select a 
generation options part. 

6. You can generate server programs in batch by specifying commands in a 
generation options file. When you use the generation UI for batch 
generation, a command file is created for you that contains one of the 
following commands: 

HPTCMD Select this command if you are generating on the local 
machine. 

CALL EFKREQ 

Select this command if you are generating on a remote 
(Generation Server) machine. 

User specified Select this command if you want to specify the name of 
the program that will control generation of the selected 
parts. The program you specify must use HPTCMD or 
CALL EFKREQ commands directly or indirectly. 
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Setting generation options from the Ul 

You can set generation options from the user interface (UI). Each target 
environment has a set of generation options available from the generation 
options notebooks. You are not required to specify values for the generation 
options because default values are provided. 

When NOOVERRIDE is specified for an option in the generation options 
defaults file, the field corresponding to that option is not available and the 
value defined in the default file is displayed. For details, refer to "Establishing 
default generation options" in the VisualAge Generator Generation Guide. 



Generating in batch for the Ul 

To generate in batch for the user interface (UI), take the following steps: 

1 . Select the VAGen part that you want to generate. 

2. Click the right mouse button and select Generate. 

3. Select Batch generation in the Generate window. The Settings button will 
be enabled. 

4. Select Settings. You must specify the following three values in order to do 
a batch generation for the UI: 

• Project name 

• Project version 

• Command file name 

For additional information on settings related to batch generation, see the 
help for the Generation Options Editor. 

5. In the Specifications box select the Add button to get a list of projects in 
the library. 

6. In the Selection required window, select the project and version that 
contains the package that contains the 4GL program and all its associates. 

7. Under Command file verify or specify the path name of the command file 
that will be created. The default is Ide\Program\GEN.CMD in the 
directory where Java is installed. 

8. Under Log file specify the path name of the log file. 



Generating on a LAN 

For LAN-based generation (EFKREQ is being used): 

1 . The generate command file is built. 

2. When the command file runs, it places a generation request file onto a 
queue that the Generation Server machine is monitoring. 
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3. The developer's machine is thus free to do other work while the 
CPU-intensive generation task is performed by this dedicated remote 
machine. 

4. Errors are logged on the LAN. 

The following REXX programs are required to generate on a LAN: 

• EFKREQ on the client 

• EFKSERV on the generation server 

• REXX on both the client and the server 

- OS/2 automatically includes REXX. 

- On Windows NT, you must install and set up REXX. 

The following environment variables pertain to LAN generation: 

• GENERATE_INI points to an initialization file. 

• EZERUSRID should be set to uniquely identify each machine in Novell. 

Default generation option values 

Default values are assigned to options that require a value but whose values 
have not been specified in any options files. 

For a list of valid options for each environment, see the online help. 
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Chapter 7. Developing GUIs with VisualAge for Java 



This chapter describes how to develop graphical user interfaces (GUIs) with 
VisualAge for Java. 

Graphical user interfaces 

A graphical user interface (GUI) program is an event-driven program that 
contains one or more windows through which program users enter data and 
request the actions performed by the program. GUI programs consist of GUI 
windows and the logic (functions) and data (records, tables) parts associated 
with the window. The GUI program calls batch or server programs to access 
files and databases. 

Defining a GUI program is different from defining character or text-based 
programs. When you develop a VisualAge Generator GUI program, you build 
the user interface visually and visually connect parts of that interface to the 
other visual and non-visual parts of the program. 

VisualAge for Java provides you with a beans palette that includes templates 
for creating many visual and nonvisual parts. VisualAge Generator adds the 
VAGen category and VAGen parts to the VisualAge for Java beans palette. 

All of the VisualAge Generator extensions to the beans palette have names 
that begin with the VAGen prefix. The basic beans palette shipped with 
VisualAge for Java is described in the VisualAge for Java online help. 

For more information on visual programming and the visual parts of a GUI 
program, refer to the VisualAge for Java task information in the online help. 
For information on defining nonvisual parts, refer to the other chapters in this 
book. 

VisualAge Generator parts category for Java 

VisualAge Generator adds the following extensions to the beans palette on the 
VisualAge for Java Composition Editor: 

• Additional VisualAge Generator parts 

• Additional features (properties and events) for parts shipped with 
VisualAge for Java 

The VAGen category, added to the menu on the beans palette when you load 
the VisualAge Generator feature, includes the following nonvisual parts: 

• VAGenRecord part 
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• VAGenTable part 

• VAGenProgram part 

• VAGenFunction part 

• VAGen Variable part 

• VAGenCommSession part 

To display these extensions, from the categories drop-down list at the top of 
the Composition Editor beans palette, select VAGen Parts. 

VAGen logic and data parts (records, tables, programs, and functions) are 
created and modified from the associated Visual Age Generator editors. You 
can also create a VAGen part from the Composition Editor by selecting the 
part icon from the beans palette and dropping it on the free-form surface. 

To define or edit a VAGen data or logic part, from the Composition Editor, 
right click on the part on the free-form surface and select open from the 
context menu or, from the VAGen Parts Browser, double-click on the part 
name. 

Other VAGen parts such as the VAGen Variable part and the 
VAGenCommSession part can only be manipulated in the Composition Editor. 

VAGen logic and data parts 

Select one of the VAGen logic or data parts to make it accessible to a 
graphical user interface. VAGen logic and data parts (records, tables, 
programs, and functions) have features (properties, events, and methods) that 
can be used in connections that control the behavior of your program. 

The following definitions will be helpful to you as you build GUI programs: 
Property 

a setting or characteristic of a bean, for example, a name, font, text, or 
positional characteristic 

Event the notification that an action by a user, program, or system has 

occurred. For example, actionPerformed is an event used to indicate 
that a user has clicked on a button 

Method 

a fragment of Java code within a class that can be invoked and passed 
a set of parameters to perform a specific task 

For more information about VAGen parts, refer to the online help. For more 
information about specific properties and events associated with VAGen parts, 
refer to the VisualAge Generator Programmer's Reference. 
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VAGenVariable part 

Select the VAGenVariable part to enable your application to pass VAGen data 
between GUI clients. A variable is a place holder for the actual bean, much 
like a parameter in an ordinary programming language. 

When you add a VAGenVariable to the free-form surface, you can specify the 
name of the VAGen part that it will hold at rim time. When you use a 
variable, you can display all the features of the VAGen part and use them in 
connections. 

For more information on the VAGen Variable part, refer to the VisualAge 
Generator Programmer's Reference. 

For more information on the Variable bean (Java), refer to the VisualAge for 
Java online help. 

VAGenCommSession part 

Select the VAGenCommSession part to indicate that you want a new 
communication session created. In order for the GUI client to use this 
communication session for server calls, you must connect the this property of 
the part to the VAGenCommSession property of the GUI client. 

For step-by-step instructions on using the VAGenCommSession part, see 
"Using the VAGenCommSession part" on page 158. For more information on 
the VAGenCommSession part, refer to the VisualAge Generator Programmer's 
Reference. 



Working with visual parts: the basics 

This section describes the basic tasks you will need to perform to build 
graphical user interfaces using VisualAge for Java and VisualAge Generator. 
For more information on building GUIs, refer to the VisualAge for Java online 
help. 

Creating visual parts and connections from VAGen Parts 

When you create GUI clients, a common task is to create connections between 
visual and nonvisual parts such as the VAGenRecord part and the 
VAGenTable part. This section discusses how to create connections between 
the user interface and the data representations. 

To create a new visual part, complete the following steps: 

1 . On the Workbench Projects tab, select the package you want to add the 
new part to. 

2. From the Selected menu, select Add+Application. 
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Note: You can select a different kind of visual part such as Applet or 
JApplet. 

The Create Application SmartGuide is displayed. The Project and Package 
fields are filled for you. 

3. In the Class name field, type the name for your new visual part. 
Create Swing based application is selected for you. 

Note: You can select AWT, but you should not mix beans from the AWT 
category with beans from the Swing category. 

4. Select Next. 

The Application Details page is displayed. 

5. In the Title bar text field, type the name you want displayed on the title 
bar. 

6. Deselect all options except Center and pack frame on screen. 

7. Select Finish. 

The window is displayed in the Composition Editor. The default size of 
the window is width: 460 and height: 300. 

To add subparts to the window and associate them with data items contained 
in a VisualAge Generator record or table, complete the following steps 

1 . From the Composition Editor beans palette, select a bean (visual part) and 
drop it on the free-form surface or an existing part such as a JPanel or a 
JWindow. 

2. On the beans palette, from the drop-down list, select VAGen Parts. 

3. Select the VAGenRecord part or the VAGenTable part. 

4. Place the part on the free-form surface. 

Note: You cannot place a nonvisual part on a visual part. 

5. On the Add Part window, specify the name of the record or table you 
want to add and select OK. 

If the part exists, you can select it from the combo box. 

6. From the context menu for the VAGenRecord or VAGenTable part on the 
free-form surface, select Connect. From the cascading menu, select the 
type of connection you want to use or select Connectable Features to 
display a complete list of properties or events. 

7. Click with mouse button 2 on the visual part you want to connect the 
VAGen part to. 

8. From the context menu select a property or an event. 
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Using Quick Form with VAGen Parts 

Using the quick form function in the Composition Editor, you can 
automatically create visual beans and connections to VAGen data parts and 
their data items. To do a quick form: 

1 . In the Composition Editor, click with mouse button 2 on a VAGen data 
part or non-array item tearoff and select Quick Form. 

2. Select the properties you want to represent on your GUI client and select 
Next or Finish. 

When you start the Quick Form SmartGuide, the "Create a new quick form" 
option selected as the default. The properties list shows only the properties 
that you can use for Quick Form. As the default, all properties shown are 
selected except "data" property. 

For the properties that are simple array items, the Swing List (JList) is selected 
as the registered quick form, but the Swing Combo Box (JComboBox) can also 
be selected. When you choose the Quick Form option from the context menu 
of a simple array item tearoff, the SmartGuide displayed with the Use an 
existing registered quick form option selected as the default. The registered 
quick form selected is the Swing List (JList). This default allows you to create 
a Swing List to display the array item. You can also choose to select the Swing 
Combo Box (JComboBox) instead. 

When you choose the Quick Form option from the context menu of a 
compound array item tearoff, the Quick Form SmartGuide is displayed with 
the Use an existing registered quick form option selected as the default. The 
registered quick form selected is the Swing Table (JTable). This default allows 
you to create a Swing Table to display the compound array item. If you do 
not want to display the compound array item in a Swing Table but want to 
display some or all of the sub items as lists, you can select the Create a new 
quick form option and work with the properties shown in the list. The Save 
Quick Form option is not available for VAGen data parts and their item 
tearoffs, and therefore, the Save Quick Form page is not available. 

Tips on connecting VAGen parts to visual beans 

Displaying VAGen data part properties: If after dropping a VAGen data 
part (record or table) on the free-form surface of the Composition Editor, no 
data item properties are displayed when you right-click on the part and select 
Connect+Connectable Features, do the following: 

• Ensure that the VAGen data part has been defined and validated and that 
all shared data items have been defined and validated. 

• Ensure that on the connection window the Property radio button is 
selected. 
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Displaying properties of torn-off data items: If not all torn-off data item 
properties are displayed on the connection windows, you might need to use a 
VAGen Variable part to make those properties available. See "Tearing off a 
property" on page 153 for information about tearing off properties. For more 
information about VAGen Variables, refer toVisualAge Generator Programmer's 
Reference. 

Displaying previously promoted features: The Promote features window 
for a bean shows only the features promoted since you opened the window. 
To view all the promoted features for that bean, select the Beanlnfo tab. 

Using property-to-property connections: When you make a 
property-to-property connection, the source event and target event are set to 
<none> unless the source or target property is bound, in which case, the 
source or target event will be left blank to indicate that it is the same as the 
source or target property. A bound property is a one that notifies interested 
parts when its value changes. If the source event of a property-to-property is 
<none>, the target property will not be updated when the source property's 
value changes. Similarly, if the target event is <none>, the source property 
will not be updated when the target property's value changes. To ensure that 
updates occur, you must specify a source or target event. To specify a source 
event: 

1 . Double-click on the connection to display the Property-to-property 
connection - Properties window. 

2. From the source event list, select an appropriate source event. 

Properties from VAGen data parts are bound, so you do not need to set 
the source or target event for the data part's end of the connection. When 
the Property-to-property connection - Properties window is displayed, if 
the data part's property is the source of the connection, the source event is 
left blank. If you select the event that matches the connecting property, 
when you save and reopen the Property-to-property connection - 
Properties window, that field will be blank again. One way to tell whether 
a property is bound or not is to look at the source or target event. If it 
shows <none> under these circumstances, the property is not bound. 

To make a connection one way, so that the data item end of the connection 
cannot be updated, change its source event (or target event, depending on 
which way the connection was made) from nothing to <none> and change 
the target event to something like keyReleased or caretEvents for a text 
field. 

Comparing the data and this properties 

The data and this attributes are defined as: 

data The data property represents the contents of the record, table, or data 
item part. 
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For an occurs item, the data property represents an ordered collection 
with the values of the valid elements of the occurs item. 

this The this property represents the part itself and contains both the data 
contents and the type description of the record, table, or data item 
part. 

For data items, the this property is represented by the name of the 
data item only. 

For parts other than data parts, the this property represents the part 
itself. 

Use the data property of the record, table, or data item if you do not need a 
type description. 

Use the this property if you need a type description. The following instances 
require a type description: 

• One of the few visual parts that requires a type description is the JTable 
part. The type description is required for the JTable part to build column 
information. 

• Similar to the JTable, the JList can be connected to the this property of a 
substructured data item. In this case, the property name must be set to the 
data property of the data item representing the JList. 

• The type description is also used for data conversion when passing 
parameters to a VAGen Program part. 

Tearing off a property 

To manipulate a bean's property in more detail than the bean allows, you can 
tear off the property. Tearing off properties is useful when properties are 
nested. It allows direct access to a property nested inside another property. It 
also allows direct access to property's events and methods. 

To work with a property as if it were a stand-alone bean: 

1 . In the Compostion Editor, click the part with mouse button 2. 

2. From the part's context menu, select Tear-Off Property. 

3. In the Tear Off Property window, select the property you want to tear off 
and select OK. 

The torn-off property appears as a stand-alone part connected to the original 
part by a property-to-property connection. The torn-off property is not 
actually a separate part; it is a variable representing the property. For 
example, you can tear off an occurs item or a substructured data item to 
access the lower level data items. 
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Handling occurs items 

Data items with an occurs value greater than one are called occurs items. An 
occurs item can be substructured, but none of the data items within its 
substructure can be defined with an occurs value greater than one. 

If you tear off the occurs item, you can use it to populate a JList or a JTable. If 
you want to use the occurs item as if it were an ordered collection, you must 
tear off the data property of the occurs item. You can then add and remove 
items from the JList or JTable, up to the maximum number of entries defined 
by the number of items within the occurs item. 

Populating a bean with Occurs Items: If you want all the items within the 
occurs item to populate a visual bean, make a property-to-property connection 
between the this property of the Occurs Item and the model property of the 
JList or the JTable. 

If you want only a range of items within the occurs item to populate the part, 
do the following: 

1 . Tear off the occurs item of the VAGen Record part or the table columns 
property of the VAGen Table part, so it exists on the free-form surface. 

2. Make an event-to-method connection between the event you want to 
trigger population of the occurs item and ihegetFieldsInRange(int, int) 
method for the occurs. 

3. Set the parameters of the connection; for example, set the starting index to 
0 and the ending index to 4, if you want to use the first five elements. 

4. Make a property-to-property connection between the result property of this 
connection and the model property of the JList or the model property of the 
JTable. 

To add or remove rows from a visual part, such as a JTable, you need to 
manipulate the model, not the visual part. If the model is an occurs item, you 
can use these methods to add or remove rows from the model: 

addNewRow After, addNeivRowBefore(int), addNewRowLastO, removeRozvAt(int) 

Note: When using an occurs item, you do not get any trailing elements that 
have the default value passed on the connection, and no blank rows 
appear at the bottom of the JList or JTable unless one of the addNewRow 
methods executes. 

For more information about using occurs items, refer to the VisualAge 
Generator Programmer's Reference. 
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Using the 4GL parts 

This section gives a brief description of the VAGen parts available from the 
VisualAge for Java beans palette. You can create 4GL parts (VAGen parts) in 
the Composition Editor or the VAGen Parts Browser. For more information on 
these parts and how to use them in building application systems, refer to the 
VisualAge Generator Design Guide. 

Using VAGen Record parts 

To access data stored in a VAGen record, drop a VAGenRecord part on the 
free-form surface and connect it to your graphical user interface. The 
following tasks explain how you can use the data items in the record. 

Using data items 

Individual data items, occurs items, and the top-level data items of 
substructured data items appear as properties of the table that you can use to 
connect to parts in your user interface. 

To access the lower-level data items of a substructured data item in a table, 
tear off the top-level data item. Consider the following example: 

Name 
ADDRESS 

STREET 

STATE 

ZIP CODE 

The only data item available as a property from a VAGenRecord part is 
ADDRESS. If you select Tear-Off Property from the pop-up menu for the 
VAGenRecord part, then select ADDRESS, you place the ADDRESS property 
on the free-form surface, making the STREET, STATE, and ZIP CODE 
properties directly accessible. 

Using the data property of data items 

A data property is also available for the individual data items. Use the data 
property when you want to modify or retrieve the data of the data item. 

The data property of a character data item in a record is the data item's value 
without the trailing blanks. Similarly, the data property of an occurs item only 
holds elements that have a value different from the default value. To include 
elements that have a default value, use one of the bounding properties. 

Using individual data items 

Use the individual data item when the connection requires a data item object, 
so that the type information can be retrieved from it. 

For example, use the individual data item in the following cases: 
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• When you want to pass the data item as a parameter to a VAGenFunction 
part. 

• When connecting a substructured occurs item to the model property of a 
JTable. 

• When you tear off data items from a record or table. These connections are 
made for you. 

Using VAGenTable parts 

To access data stored in a VAGen table, drop a VAGenTable part on the 
free-form surface and connect it to your graphical user interface. The 
following tasks explain how you can use the data items in the table. 

Using data items 

Individual data items, occurs items, and the top-level data items of 
substructured data items appear as properties of the record or table that you 
can use to connect to parts in your user interface. 

To access the lower-level data items of a substructured data item in a record, 
tear off the top-level data item. Consider the following example: 

Name 
ADDRESS 

STREET 

STATE 

ZIP CODE 

The only data item available as a property from a VAGenTable part is 
ADDRESS. If you select Tear-Off Property from the context menu for the 
VAGenTable part, then select ADDRESS, you place the ADDRESS property 
on the free-form surface, making the STREET, STATE, and ZIP CODE 
properties directly accessible. 

Using the data property of data items 

A data property is also available for the individual data items. Use the data 
property when you want to modify or retrieve the data of the data item. 

The data property of a character data item in a record is the data item's value 
without the trailing blanks. Similarly, the data property of an occurs item only 
holds elements that have a value different from the default value. To include 
elements that have a default value, use one of the bounding properties. 

Using individual data items 

Use the individual data item when the connection requires a data item object, 
so that the type information can be retrieved from it. 

For example, use the individual data item in the following cases: 
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• When you want to pass the data item as a parameter to a VAGenFunction 
part. 

• When connecting a substructured occurs item to the model property of a 
JTable. 

• When you tear off data items from a record or table. These connections are 
made for you. 

Using VAGen Program parts 

Programs are essentially visual wrappers for what used to be the VAGen 
CALL statement with the REPLY option set. Programs can be placed on the 
free-form surface to allow visual connections from GUI client applications to 
server applications. 

For example, you can visually code a request to read from a customer 
database by making an event-to-method connection from the actionPer formed 
event of a Push Button to the execute method of a VAGenProgram part. The 
VAGenProgram part could be a VisualAge Generator called batch application, 
which accepts the customer number as a parameter, reads the customer 
database, and returns the appropriate customer record. The parameters on the 
event-to-method connection can be specified visually as well. 

VAGen Program parts can be local or remote VisualAge Generator called 
batch programs, or local non- VisualAge Generator external programs. 

Using VAGenFunction parts 

Consider the following example of connecting a Push Button to a 
VAGenFunction part. If you make the following connections, you need to be 
aware of the order in which you make the connections: 

• Make an event-to-method connection between the actionPer formed event of a 
Push Button and the data item of a VAGenRecord part. You supply a 
constant parameter of 1 for the connection. 

• Make an event-to-method connection between the actionPer formed event of 
the same Push Button and the execute property of a VAGenFunction part. 

The order of connections in this example is critical so that the parameter value 
of 1 is in the data item before the function is run. Thus, you must make sure 
that the data item connection is made before the function connection. Use the 
Reorder Connections From window to put the connections in the necessary 
order. 

For more information on connections, refer to the VisualAge for Java online 
help. 
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Using VAGen GUI parts 

This section describes tasks you need to perform using VAGen parts that are 
only available in the Composition Editor. 

Managing communication sessions 

By default a new communication session is created for each bean (instance) 
that performs a call to a server program from a VAGenFunction part or 
through a connection from a VAGenProgram part. To share the same 
communication session between multiple beans, do one of the following: 

1 . Connect the VAGenCommSession properties of two different beans. 

2. Use the VAGenCommSession part for one or more beans on the free-form 
surface of one bean and connect its this property to the 
VAGenCommSession property of each of the beans that should use this 
session. 

Connecting the VAGenCommSession properties of two beans 

To connect the VAGenCommSession properties of two different beans: 

1 . From the beans palette, select Choose Bean. 

2. On the Choose Bean window, select the Bean Type Class. 

3. Select the Browse button to display the Choose a valid class window. 

4. Select the bean you want to share a communication session. 

5. Select OK and place the bean on the free-form surface. 

6. Click with mouse button 2 on the free-form surface of the first bean. 

7. From the context menu, select ConnecHConnectable Features. 

8. From the Start connection from window, select the VAGenCommSession 
property. 

9. Select OK and click with mouse button 1 on the new bean. 

1 0. From the context menu, select Connectable Features. 

1 1 . From the End connection to window, select the VAGenCommSession 
property and select OK. 

Using the VAGenCommSession part 

To connect a visual bean to a VAGenCommSession part: 

1 . From the beans palette drop-down list, select VAGen Parts. 

2. From the beans palette, select the VAGenCommSession part and place it 
on the free-form surface. 

3. Click the VAGenCommSession part with mouse button 2 to display its 
context menu. 

4. Select Connect+this and click with mouse button 1 on the free-form 
surface. 
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Alternatively, you can select a variable representation of another visual 
bean and continue with the following steps. 

5. From the context menu select Connectable Features. 

6. From the End connection to window, select the VAGenCommSession part 
property 

Invoking VAGen scripts from VAGen parts 

One of the best ways to signal GUI events from VAGen parts is through a 
VAGen Script. A VAGen Script is an instance method that accepts no 
arguments and is associated with the class you select when you create it. 
Using EZESCRPT you can synchronously execute code written in Java. To 
execute a VAGen Script from a VAGen function: 

1 . Create a new visual part or open an existing one. 

2. Add a VAGenFunction part to the free-form surface, define it, and include 
a statement to execute your VAGen Script. For example: 
EZESCRPT("scriptName") 

or 

EZESCRPT(dataltem) 

Here "scriptName" is the string literal name of the VAGen Script and 
dataltem is the data item into which the script name string was moved. 

3. Add and connect the visual part that will execute the logic part. For 
example, if you are using a button, connect its actionPer formed event to the 
logic part's execute property. 

Note: Ensure that you have selected the class to which you want to add a 
new method before you start building a VAGen Script. 

4. Create a VAGen Script with the name you specified in your logic part. You 
can type a script directly into the VisualAge for Java Source Pane or use 
the VAGen Script Wizard to help you compose one. 

Using the VAGen Script Wizard 

VisualAge Generator provides you with a VAGen Script Wizard that makes it 
easy for you to write simple Java code. Just start the VAGen Script Wizard 
and step through its instructions. The VAGen Script Wizard is available from 
any menu where you can select Method Template. To start the VAGen Script 
Wizard: 

1 . Select a project 

2. From the Workbench Selected menu, select Add, then Class, Applet, 
Application, or Interface to display a wizard to help you create a new 
visual part. If you select Class, select Compose the class visually. 

3. Drop your parts. 

4. From the Bean menu select Save Bean. You must save new beans at least 
once before you can use the VAGen Script Wizard . 



Chapter 7. Developing GUIs with VisualAge for Java 159 



Note: If the class to which you want to add a script has already been 
created, open it in the Visual Composition tab. 

5. With the part open in the Visual Composition tab, select the Members 
tab. 

6. Select the Members (or Class) menu, then VAGen Script Wizard. 
The VAGen Script Wizard is displayed. 

As you follow the wizard's steps, the appropriate object-oriented statements 
are displayed in the Composed Script area. When you have completed the 
script, select Finish to have the method generated for you and stored in the 
appropriate object or class. 



Error handling 

When a problem occurs during execution of your GUI client, an exception is 
produced and is handled by whatever exception handlers are in place for the 
bean. By default, the handleException() method of the bean will be invoked. 
Within the VisualAge for Java IDE, if a VAGen part is the source of the 
exception, and the "Test GUI clients using runtime mode" option is not 
selected, the exception and stack information will be displayed in the Console 
window. It is possible, however, to have the Java debugger invoked when an 
exeception is produced. To use this option: 

1 . On the Workbench toolbar, select the test button. 

2. Select the Exceptions tab. 

3. From the list, select any exceptions you want to suspend execution and 
display the debugger. 



Testing GUI clients on Java 

The following are several important differences you will notice in the 
behavior of the VisualAge Generator Test Monitor when you use it to test 
client code that uses VisualAge Generator parts: 

• The Test Monitor is only opened when VisualAge Generator logic is 
invoked. This means that when a GUI is invoked for test from either the 
Workbench or from the Composition Editor the VisualAge Generator Test 
Monitor will not be opened unless the show processing on the GUI caused 
VAGen logic to be invoked. 

• Shutting down the Test Monitor will not affect the GUI client being tested. 
In versions prior to VisualAge Generator V3.0, when the Test Monitor was 
closed, the entire test shutdown. Now you must shutdown the GUI client to 
quit the test. If the shutdown processing invokes VisualAge Generator logic, 
then a new Test Monitor will open and run the requested logic and then go 
into "Test Complete" state when GUI client is gone. 
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• When the VisualAge Generator Test Monitor is invoked for the first time, it 
is opened minimized. 

• The Break On Event Entry option is OFF by default. However, there is a 
preference on the VAGen - Test Linkage preference page that enables you 
to set it ON by default. The main point to consider is that Test Monitor will 
run continuously in the background unless one of the following occurs: 

- A User Break is invoked. 

- A breakpoint is encountered. 

- An error message is issued during processing. 

In all of the above cases, the Test Monitor will come to the foreground with 
the currently executing statement highlighted. 

• Invoking a new test session does not affect other test sessions. In versions 
prior to VisualAge Generator V3.0, each invocation of a new test would 
cause the previous test to shutdown. 

Testing considerations for VAGen scripts 

Using VAGen scripts allows the synchronous execution of Java / Smalltalk 
scripts from within VAGen functions that are invoked by GUI clients. When 
an EZESCRPT statement is encountered in a VAGen GUI client function, test 
facility makes a "call" to a Java / Smalltalk script. Scripts that can be invoked 
this way are public instance methods (not static methods) or instance methods 
that accept no parameters and are stored on the GUI client class. Any client 
data modifications that have been made are signaled at this point and then 
the script is executed. 

Either the signalling of data modifications or the script itself can cause other 
VAGen functions or programs to execute. It is now possible for the system to 
begin execution of a VAGen event while in the middle of executing another 
VAGen event. The new event is processed and then control returns to the GUI 
client to continue either the data modifications or script execution. When the 
GUI client has completed execution of the script, control returns to the 
original function that contained the EZESCRPT statement. 

There are several important differences you will notice in the behavior of the 
VisualAge Generator Test Monitor when you use it to test client code that 
uses VAGen scripts: 

• When EZESCRPT statements trigger other VisualAge Generator logic 
events, the same Test Monitor window is displayed and the subsequent 
VAGen functions or programs are shown in the Execution Stack Monitor. 
When you use the Execution Stack Monitor to view the history of VAGen 
logic execution, you can see the original function that contained the 
EZESCRPT statement that is in the middle of processing. This behavior is 
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very similar to the way function or CALL statements are handled. The 
identifier, '(from script)' is displayed at the end of the Execution Stack 
monitor entry to show which logic events were triggered indirectly by an 
EZESCRPT statement. 

• Shutting down the Test Monitor while you are testing a VAGen logic event 
triggered by an EZESCRPT statement will not affect the GUI client being 
tested. That particular logic event is canceled, but control is returned to the 
GUI client to continue script processing. If the GUI client invokes another 
VisualAge Generator logic event, then a new Test Monitor will open and 
run the requested logic. You must shutdown the GUI client to quit the test. 

• If the Smalltalk script called by the EZESCRPT statement has an error, test 
facility does not attempt to mask the error. Instead, the VisualAge Smalltalk 
debugger window opens with the error displayed. You can fix the script 
error and select Resume to continue the test. Control will return to the Test 
Monitor when the GUI client script is finished executing. If you close the 
debugger without resuming, the Test Monitor will be left up but will be 
unusable. You can shut down the Test Monitor yourself or it will be closed 
at a later time. If other VisualAge Generator logic events are invoked, a 
new Test Monitor will be opened. 

• If the Java script called by the EZESCRPT statement has an error, test 
facility does not attempt to mask the error. Instead, the exception will be 
caught and handled in the normal test facility manner. The Test Monitor 
will be left up, but will be unusable. You should use the VisualAge for Java 
debugger to terminate the GUI client, which will shut down the Test 
Monitor. After fixing the script error, you can restart the GUI client test. 

• If you reposition the test, or save a VisualAge Generator part that causes 
the test facility to reposition the test, while you are executing an EZESCRPT 
statement or executing logic events triggered by an EZESCRPT statement, 
the Java/Smalltalk script is canceled and no other script statements are 
executed. This means that any other VisualAge Generator logic events are 
not invoked. If the test was repositioned prior to the EZESCRPT statement, 
you can continue testing to execute the statement again and completely test 
the script. 



Generating GUIs in VisualAge for Java 
Generating VAGen run-time code 

Every time you save your visual part or nonvisual part, VisualAge for Java 
generates run-time code, which describes the visual parts, nonvisual parts and 
connections contained in it. If your part contains VAGen data parts or VAGen 
logic parts, the VisualAge for Java run-time code contains their names but no 
other detailed information about them. To run the part, the VAGen run-time 
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code has to be generated because it is this code that describes all data items in 
each VAGen data part, all statements in each VAGen logic part and other 
important information about them. 

You can choose to generate VAGen run-time code for a bean or all beans that 
contain VAGen data or logic parts in a package. You can also generate 
run-time code for the beans in several packages or for the beans in all the 
packages in a project. To generate VAGen run-time code for a bean: 

1 . On the Workbench, select the project, package, or packages that contain 
the classes for which you want to generate VAGen run-time code. 

2. From the Selected menu, select Generate + VAGen Runtime Code. 

3. In the Generate VAGen Client Runtime Code window, all classes are 
selected by default. Deselect any classes you do not want to generate 
run-time code for. 

To specify a linkage table to be used while generating the run-time code, 
create a Generation Options part and include the /LINKAGE option in it. 
Then, specify this Generation Options part to be used for run-time code 
generation. To specify the Generation Options part: 

1 . From the VAGen Parts Browser Window menu, select Options. 

2. Select Generation to display the Generation page. 

3. From the Client group box, select the generation options part you want to 
use. 

If VAGen run-time code has been generated for a part, you can choose to test 
your parts using the run-time code and bypass the Interactive Test Facility. 
This allows you to verify how your parts will work at run time before you 
package your application. To set this option: 

1 . From the VAGen Parts Browser Window menu, select Options. 

2. Select Test to display the Test page. 

3. From the Options group box, select Test GUI clients using run-time 
mode. 

Note: Testing using the run-time code bypasses the Interactive Test Facility 
for all parts including server programs, and you will need to already 
have generated the server programs and performed all setup needed to 
call them. 

You will have to generate VAGen run-time code for all parts containing 
VAGen data or logic parts before you can successfully export your client for 
run time. If a part's VAGen run-time code is missing or contains changes that 
require generation, the Export VAGen client menu choice on the Workbench 
Selected menu will not be available. 



Chapter 7. Developing GUIs with VisualAge for Java 163 



While generating VAGen run-time code any table parts that are on your visual 
part or nonvisual part will automatically be generated by default. If you do 
not wish to generate the tables along with the run-time code, specify the 
/NOGENTABLES option in a Generation Options part and select this options 
part to be used when generating the run-time code. 

Generating GUI parts 

To generate VAGen parts used by a graphical user interface (GUI), do the 
following: 

1 . In the Workbench window, select a Java class that contains VAGen parts 
used by a GUI. You can do this either of the following ways: 

• From the Packages tab, select an item from the Types menu. 

• From the Classes tab, select an item from the Class Hierarchy menu. 

2. On the menu bar, select Types (with the Packages tab) or Classes (with the 
Classes tab), or click mouse button 2. 

3. Navigate the menus as follows: Generate -> VAGen Runtime Code... 
Generating 4GL Java clients 

This section deals with the following topics: 

• Overview of 4GL Java clients 

• Generating 4GL Java parts 

• Setting properties 

• Considering incompatibilities 

Overview of 4GL Java clients 

VisualAge Generator 4GL Java client generation lets you define and generate 
4GL GUI programs and table parts as Java code (or parts) to be run in a 
Java-enabled environment. A typical user scenario of 4GL Java client 
generation in a business environment is as follows: 

1 . Define a GUI program that uses 4GL parts. 

2. Test the GUI program. 

3. Generate Java byte codes for the GUI program parts. 

4. Deploy the generated byte codes to a target platform. 

5. Install 4GL Java Work Group Services (WGS) on the target platform. WGS 
is a subpart of the 4GL Java Client Generation component. This is a 
one-time installation. 

6. Run the generated GUI program in a Java-enabled environment. 
Generating 4GL Java parts 

The 4GL parts referenced by a GUI (View) in a free-form surface are 
generated into the repository of VisualAge for Java. They can be extracted by 
the user as Java source (.java) files, Java byte codes (.class files), or a Java 
archive (.jar) file. 
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For a given user defined 4GL part name (for example, NNNN), the naming 
conventions for the generated Java classes are as follows: 



Type of part 


Class name format 


Working storage 


VGWkgNNNN 


Table 


VGTblNNNN 


File 


VGFileNNNN 


SQL 


VGSqlNNNN 


DL1 


VGD11NNNN 



All 4GL functions used in a GUI view are generated as methods within a 4GL 
GUI class, for example, VGGuiNNNN where NNNN is the name for the GUI 
part. A function named "FOO" is generated as a method named "funcFOO" in 
the generated 4GL GUI class. The generated 4GL GUI class contains references 
to all the generated 4GL Java parts defined in the free-form surface and it also 
serves as an interface between the generated Java GUI part and the 4GL parts. 
Related generated 4GL Java parts are grouped as members of a Java package 
and can be deployed to platforms supported by 4GL Java Work Group 
Services. 

Setting properties 

Before running a generated 4GL Java part, you can set properties that affect 
the run-time behavior of 4GL WGS. These properties are described below. 
They are specified vgj. properties, a text file that contains key-value pairs of 
properties. You can use a text editor to modify the settings. 

NLS properties: You can display run-time error or informational messages in 
the languages supported by the WGS. To set the language, specify an NLS 
code as the value for the key vgj.nls.code. If vgj.nls.code is not set, an attempt 
is made to set the NLS code based on the program's default Locale. If all else 
fails, ENU (United States English) is used. 

You can also specify the decimal point symbol by defining a value for 
vgj.nls.number.decimal. Only the first character of the value is used. If the 
property is not set, a decimal symbol appropriate for your NLS setting is 
used. 

Trace properties: The use of trace properties is primarily intended for system 
administrators and program developers to diagnose potential run-time 
problems of a generated 4GL Java part. The trace information currently 
includes a time stamp, the name of the GUI program part, the name of the 
function part (if applicable), and any error messages the program might have 
encountered during execution. To trigger the trace, define a value for the key 
vgj. trace. type. The possible values for vgj. trace. type are numbers between 0 
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and 15. A value of 0, the default setting, means that no trace is enabled. You 
can turn on various kinds of tracing by setting bits in the value, as follows: 



Bit 


Value 


Form of tracing 


1 


1 


General 


2 


2 


EZE math functions 


3 


4 


EZE string functions 


4 


8 


Table loading 



If a trace is enabled, vgj.trace.device. option determines where the information 
will be written. The following table shows the meaning of the values: 



Value 


Output 


0 


System.out 


1 


System.err 


2 


File 



The name of the file is specified in the property vgj.trace.device. spec. This 
property is ignored when vgj.trace.device. option is not 2. If there is an error 
opening the file, the output is sent to System.err instead. 

Date mask properties: The functions EZEDAYLC and EZEDTELC require 
you to define date masks. The date-mask properties are named in part 
according to the NLS setting for which they are defined. The properties are 
named vgj.datemask.gregorian.long.xxx and vgj.datemask.julian.long.xxx, 
where "xxx" is the NLS code. This means that a set of date masks can be 
defined for each NLS code, in the same properties file. 

The long Gregorian date mask defaults to 'MM/DD/YYYY', if it is not 
defined; however, first an attempt is made to find a date mask using Java's 
built-in text formatting utilities, based on the NLS code. The long Julian date 
mask defaults to 'DDD/YYYY', and no extra attempt is made to find one. 

PowerServer location property: The vgj.powerserver. location property 
specifies the type of PowerServer session to establish, as defined below in the 
description of CALL. If this property is not set or is equal to NONE, the type 
of session that the CALL statement will establish is a local one. Otherwise, the 
property specifies the domain name of an RMI server through which a remote 
session will be established. For applets, this property must be set to the web 
server from which that the applet is loaded. 
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Considering incompatibilities 

4GL Java WGS is a new run-time library supported by VG. In most cases the 
Java WGS implements the exact language syntax and semantics defined by 
VG. However, a few incompatibilities exist. They are listed below: 

• The BIN items always store their data in big-endian format (most 
significant byte first), no matter what byte ordering the underlying machine 
uses. 

• The data of HEX items used as parameters to the EZE math functions are 
converted to and from numbers by treating their bytes as if they were in 
big-endian format, no matter what byte ordering the underlying machine 
uses. 

• The CHA, NUM, and NUMC items store their data using the machine's 
default character set. Thus the results of comparisons can vary from 
platform to platform. 

• Table generation for the Java 4GL client environment now creates two files. 
The first is a definition file and the second is a content file. The definition 
file is the Java class that represents the table. The content file contains the 
table's data. 

The generated table content file must be deployed in a directory that is 
accessible by the JVM. In the case of running a Java application, the 
CLASSPATH environment variable needs to include the directory where the 
table content can be located. While in the case of running an applet, the 
CODEBASE parameter of the HTML tag has to include the location of the 
table content file. 

Additionally, the initial release of the Java 4GL client generation introduces 
a new format for table files. Both the new format and the original format 
can be used by Java programs; therefore existing table data does not need 
to be regenerated. To use an old-style table content file, it must have been 
generated for a big-endian system that uses the same code page as your 
JVM. 

• The way a Java program's CALL statement is interpreted depends on the 
linkage table and properties file. If no entry exists in the linkage table for 
the program, or if an entry exists but it does not include a linktype, the 
called program is invoked through the JVM. It must be an executable or 
script file on the local machine. Executables and scripts are located by the 
operating system in a system-dependent way, usually through the PATH 
environment variable. Programs called in this way have no access to the 
console. 

When calling a script file on Windows NT or OS/2 , you should include the 
command echo off at the beginning of the script. 

The other kind of CALL is used to call a program in a local library (.dll or 
.so) or a server application. This is implemented using an existing C library, 
the PowerServer API. 
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CALL commands that use the PowerServer API use one of two session 
types, a local session or a remote session. In a local session, the property 
vgj.powerserver. location is set to NONE or is undefined. This means that 
the C library for the PowerServer API is loaded by the calling application. 
Because security constraints on applets will not allow this to occur, a 
remote session is needed. In a remote session, Remote Method Invocation 
(RMI) is used to open a session on the RMI server named by 
vgj.powerserver. location. The RMI server program loads the PowerServer 
API, indirectly allowing the calling applet to use its services. 

The linkage table entry for this type of CALL must include 
linktype=CSOCALL. Use remotecomtype=DIRECT to load a .dll or .so file 
on the machine where the PowerServer API was loaded. 

There is a new RMI server for the remote sessions called SessionManager. 
The SessionManager provides similar function to the version 3.1 
SessionManager provided with the Server Wrapper library, but with more 
flexibility. The new SessionManager will use a properties file called 
csosessionmanager.properties for NLS and Trace settings. It will provide a 
GUI interface for session management and statistics gathering. 

For additional information about the new SessionManager, refer to the 
VisualAge Generator Client/Server Communications Guide. 



Running a generated Java program outside VisualAge for Java 

This section explains how to run outside VisualAge for Java a Java program 
generated by VisualAge Generator Developer. 

Terminology 

This subsection defines Java terms used to describe how to run a generated 
VisualAge Generator Java program outside VisualAge for Java. If you are 
already familiar with these terms, you can skip this subsection. 

applet A java program that does not stand alone; rather, it is run 

inside a web browser or the appletviewer program. The main 
class of an applet is a subclass of Java's Applet class. GUIs 
made in VisualAge for Java can be run as both applets and 
applications. 

application A java program that can be run without a browser or 

appletviewer. The main class of an application may be a 
subclass of Java's Applet class, but it does not have to be. 
GUIs made in VisualAge for Java can be run as both applets 
and applications. 

fully-qualified name 

The name of a class's package, followed by a period (.), 
followed by the class name. Package names can have multiple 
parts, and each of them is separated by a period. For example, 
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the fully-qualified name of the Applet class is 
java.applet.Applet, because Applet is in the package 
java.applet. 

JDK Java Development Kit, a group of utilities that includes tools 

for running, compiling, and developing Java programs. 

JFC Java Foundation Classes, a group of useful Java classes 

written by Sun Microsystems. The JFC includes Swing. 

JRE Java Run-time Environment. It is like the JDK but includes 

only the tools for running Java programs. 

JVM Java Virtual Machine, a program, such as java.exe or 

appletviewer.exe, which can run compiled Java code. This is 
included in JDK and JRE. 

main class For an application, the class that contains the method that is 
called "main" and is the first method executed when the 
program starts. For an applet, the class that is a subclass of 
Java's Applet class and which usually contains the code that 
creates its GUI. 

Swing The name for a group of Java GUI components written by Sun 

Microsystems. It includes things like buttons, scrollbars, and 
windows. All generated VisualAge Generator GUIs require 
Swing. 

Starting quickly 

If you want to get your programs running as soon as possible and do not care 
whether they are applets or applications, perform the following steps: 

1 . Set up your environment as described in the next section. When you get to 
Step 3, install the JDK instead of the JRE, because you will be running 
your programs as applications. Running programs with the JDK is a little 
easier than running them with the JRE. 

2. After your environment is set up, develop your program. 

3. When you are done, perform steps 2 and 5 of the section called Deploying 
a program. 

Setting up the environment 

These steps only need to be performed once. They must be done before you 
can run your programs outside VisualAge for Java. 

1 . Install the VisualAge Generator Server component on your system. (See 
the VisualAge Generator Installation Guidefor installation instructions. )The 
CLASSPATH will be set during installation. 

2. Customize vgj. properties as required for your environment. Comments in 
the file describe what effect the properties have on programs as they run. 

3. Install your JVM. 
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If you want to run applets, you need a web browser or the appletviewer 
program that comes with the JDK and JRE. 

If you want to run applications, you need a program like java.exe that 
comes with the JDK or jre.exe that comes with the JRE. 

Notes: You need a JVM that runs version 1.2 of Java or higher and a Web 
browser that supports this version. 

Sun's JDK can be downloaded from: 
http://java.sun.eom/products/jdk/l.2 

Sun's JRE can be downloaded from: 
http://java.sun.eom/products/jdk/l.2/jre 

The Web browser you use must support Java version 1.2 or later. 
The most recent version of Netscape and Internet Explorer (IE) 
may support this version of Java. You can also use the Hotjava 
browser instead of Netscape or IE. Hotjava is written in Java and 
will run on any system with Java version 1.1.6 or later installed. 

Hotjava can be downloaded from: 
http://www.javasoft.eom/products/hotjava/i ndex. html 

If you must use Netscape or IE, you can use the Java plug-in that 
is included with the JDK and JRE. Under this configuration, 
instead of the browser running your applet, the plug-in runs it 
using a newer version of the JVM. 
See the section on deploying a program for instructions on how to modify 
an HTML file to activate the plug-in. The plug-in works only on Windows 
and Solaris. 

4. Install Swing. All generated VisualAge Generator GUIs require version 
1.0.3 of Swing. The Swing code is in a file called swingall.jar in 
IBMVJava\hpj\lib. It can be downloaded as part of the JFC from 
http://java.sun.com/products/jfc/download-lB3.html 

To run applets or applications, swingall.jar and hpt.jar must be located on 
the same system as the applet or application. On a Windows or OS/2 
system, the three must reside on the same drive. On a host system such as 
VM, the three must reside on the same disk. 

5. If you want to run applications, you need to set your CLASSPATH 
environment variable. 

The CLASSPATH variable is used to tell the JVM running an application 
where the application's code is. CLASSPATH is a list of directories, Jar 
files, and Zip files. 
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On Windows and OS/2, each entry in CLASSPATH is separated by a 
semicolon. 

On AIX, HP-UX, and Solaris, each entry in CLASSPATH is separated by a 
colon. 

During installation, CLASSPATH variable is updated to include hpt.jar and 
the directory into which Common Services was installed (the Common 
Services installation directory is needed so that the VisualAge for Java 
code can locate vgj. properties). 

At the very least, you must add swingall.jar to your CLASSPATH variable. 
Adding the current directory (.) is often useful. For example, if you are 
using Windows or OS/2 and you installed Common Services in c:\www\ 
and Swing in c:\www\swingl03\ and you added . to the CLASSPATH 
variable, it would look something like this: 
. ;c:\www;c:\www\hpt . jar;c: \www\swingl03\swi ngal 1 .jar 

Deploying a program 

To extract a program from VisualAge for Java and run it, perform the 
following steps: 

1 . If your program is an applet, make sure its HTML file contains its correct 
width and height. 

a. View the applet's properties in the VisualAge for Java Visual 
Composition Editor. The width and height are listed as part of the 
"constraints" property. 

b. Return to the Workbench, right-click on the applet class, and choose 
"Properties." On the Applet tab of the Properties dialog, make sure the 
WIDTH and HEIGHT values match those you saw in the editor. 

2. Export the code. 

a. From the Workbench, right-click on the main class of your program. 

b. Choose "Export VAGen Client" from the menu. 

Note: The part's VAGen run-time code must exist or this option will 
not be available. 

c. Choose "Directory" or "Jar file" and left-click Next. If you choose to 
export to a Jar file, your code will be exported as a single Jar file. Jar 
files can dramatically improve the performance of applets run in 
browsers, because they reduce download time. 

d. Enter the name of the directory or Jar file to which you want to export 
the code. If you are exporting an applet, choose a location somewhere 
in the same disk drive as hpt.jar. For example, if hpt.jar is in c:\www\, 
you should export to somewhere on your c: drive, such as 
c:\www\gui\ or c:\www\gui\gui.jar. 
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e. Check the .class and resource boxes, and uncheck the .java box. If you 
want to run your GUI as an applet, check the .html box. If you are 
exporting to a Jar file, check the "Compress the contents of the Jar file" 
box. 

f. Confirm that no extra classes were selected: press each "Details..." 
button and make sure that the files you are about to export belong to 
only your projects. If classes or resources from other projects are 
selected, uncheck the boxes next to their projects' names. 

g. Press Finish. 

3. If your program is an applet, modify its HTML file before running it. 

a. Change the ARCHIVE attribute of the APPLET tag so that the JVM 
knows where to find your Jar files. The ARCHIVE attribute is a 
comma-separated list of paths to your Jars. They must have some 
parent directory in common. This common parent directory is known 
as the "code base," and the ARCHIVE attribute tells how to get from 
the code base to the Jars. For example, if you installed hpt.jar in 
c:\www\ and swingall.jar in c:\www\swingl03\ and exported your 
program as Jar in c:\www\gui\gui.jar, your code base is c:\www\ 
and your ARCHIVE list is hpt.jar,swingl03/swingall.jar,gui/gui.jar. 
(Notice that the directories in the ARCHIVE are separated by / rather 
than \. This is because the ARCHIVE is a list of Uniform Resource 
Locators (URLs), and URLs use / to separate the names of directories.) 
If you export your program to a directory (for example, c:\www\gui\) 
instead of to a Jar, your code base is c:\www\ and your ARCHIVE list 
is hpt.jar,swingl03/swingall.jar. 

b. If the code base is not the directory where your applet's HTML file 
resides, you must indicate how to find it by specifying the CODEBASE 
attribute to the APPLET tag. Continuing with the example above and 
assuming the HTML file is in c:\www\gui\applet\, the CODEBASE 
attribute is ../.. (the code base is c:\www\, which is two directories 
above c:\www\gui\applet). The APPLET tag in the HTML file looks 
something like this: <APPLET CODE=com.xyz. client. ClientGUI. class 
ARCHIVE=hpt.jar,swingl03/swingall.jar,gui/gui.jar CODEBASE=../.. 
WIDTH=426 HEIGHT=240> 

4. If your program is an applet and you want to use the Java Plug-in, more 
modifications to the HTML file are required. This is because the plug-in is 
not activated when the browser sees an APPLET tag. The easiest way to 
make the changes is to use the HTML Converter tool that can be 
downloaded from the same page as the plug-in. (If you want to do the 
conversion manually, see 

http: / /www.javasoft.com/products/plugin/1.1.2/ docs/tags.html.) If 
someone loads a page designed to use the plug-in but it is absent, the 
browser will point them to a page from where it can be installed. The 
plug-in requires Netscape or Internet Explorer on Windows or Solaris. 
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5. You are now ready to run the program. 

a. To run an applet in a browser, have the browser load the applet's 
HTML file. To run an applet in the appletviewer, run the cd command 
to go to the directory containing the applet's HTML file and type 
"appletviewer" on the command line, followed by the HTML file's 
name, as in appletviewer gui.html. 

b. Before you run an application, you must run the cd command to go to 
the directory where its code was exported. Alternately, you can include 
the directory in your CLASSPATH and rim the program from any 
directory. 

C. To run an application by using the JDK, type java on the command 
line followed by the fully-qualified name of your main class, as in 
java my.pkg.GUI. Running an application using the JRE is similar to 
running it with the JDK, but you must use the -cp switch when you 
start the program so that it will use the CLASSPATH environment 
variable. For example, you can modify the example above as follows: 
jre -cp %CLASSPATH% my.pkg.GUI (on Windows) or 
jre -cp $CLASSPATH my.pkg.GUI (on AIX). 

Transferring control in GUI client programs 

VisualAge Generator supports transferring control between GUI client 
programs and generated C++. 

Migrating GUI clients in VisualAge for Java 

In order to use VisualAge for Java GUIs developed with previous releases of 
VAGen, you need to use the migration tool to migrate them so that they are 
consistent with JDK 1.2. 

To migrate your GUI clients complete the following steps: 

1 . On the VisualAge for Java Workbench, select the projects, packages, or 
classes you want to migrate. (We recommend that you migrate at the 
Projects level so that both your GUI client classes and their associated 
beanlnfo classes can be migrated at the same time.) 

2. Click with mouse button 2 on the area where you made your selections. 

3. From the context menu, select Reorganize-»Fix/Migrate. 

4. On the Fix/Migrate Class(es) SmartGuide, select the Include JDK 1.2 
renamed packages checkbox. 

5. Select Finish. 

If migration results in warnings or errors in the migrated classes (displayed 
with red x's), it could be because of one or more of the following reasons: 

• The GUI client classes contain warnings or errors before migration starts 
due to reasons that have nothing to do with changes for JDK1.2. For 
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example, some classes that are referenced by these migrating GUI client 
classes are in another project which has not been added to the workspace. 

• The GUI client classes reference classes that have not been migrated. 
For more information, see the VisualAge for Java Migration Guide. 
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Part 3. Using VisualAge Generator Developer on 
Smalltalk 
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Chapter 8. Managing VAGen parts in VisualAge Smalltalk 



Creating an ENVY application 

VisualAge Generator stores VAGen parts in ENVY applications. Before you 
build a new VAGen part, you must create a new application or load an 
edition of an application to contain the parts you build. 

When you start VisualAge Generator, two windows will be displayed on your 
desktop: the System Transcript window and the VisualAge Organizer window. 

To create a new application: 

1 . On the VisualAge Organizer window, select Applications ■» New. 

2. In the New Application window Name field, type a name for the 
application. 

Note: A common convention for naming ENVY applications is to 

capitalize the first letter of the name and the first letter of any 
additional words in the name. For example, the default name 
displayed in the New Application window is MyApplicationl. The 
name should not contain any spaces and you cannot have two 
applications with the same name in the same library. Check with 
your development leadership for more specific naming guidelines. 

By default the Subapplication of checkbox is not checked. Using 
subapplications can make library management easier if you are working 
with applications that contain parts you do not plan to share. To create a 
subapplication, select the checkbox and specify the name of the application 
you want to contain it. 

3. Select OK. 



Importing applications 

To use VAGen parts, you must import and load the ENVY application that 
contains them. 

Note: If the application containing the parts already exists in the library, you 
need to move the application into your image. After you import an 
application, you must load it into your image before you can work 
with the parts. 

To import an application into the library: 
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1 . From the Applications menu, select Import/Export ■* Import Applications. 

Note: A prompt containing the IP address of the ENVY server system is 
displayed. If you are using a stand-alone system, a system file 
selection window is displayed, so you can skip the following step. 

2. Select OK. 

3. In the File name field, type the complete path name to .DAT file that 
contains the application you want to use. 

4. Select Open. 

5. From the Names pane, select the application you want to use. 

6. From the Versions pane, select the version of the application. 

7. Use the arrow button to place the selected version of the application in the 
Selected Versions pane. 

8. Select OK. 

Alternatively, you can create a batch command to import the external source 
format of your parts. 



Loading applications 

To use VAGen parts, you must load the ENVY application that contains them 
into your image. To load an application: 

1 . From the VisualAge Organizer window, select Applications ■* Load ■* 
Available Applications. 

2. From the Names pane, select the application you want to load. 

3. From the Editions pane, select the edition you want to load. 

4. Use the arrow button to place the edition in the Selected Editions pane. 

5. Select OK. 

Note: If you try to load an application that contains a VAGen part with the 
same name as one that you already have loaded in your image, the 
load will fail. If the parts contained by two applications are identical, 
create a new application to contain the common parts, delete those 
parts from the two applications, and make the new application a 
prerequisite for the other two. If the parts are different but have the 
same name, you can rename one of the parts by opening it and using 
Save As. 

For more information on managing applications, refer to the IBM Smalltalk 
User's Guide. 
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Working with VAGen parts 

A part consists of both a name and a complete definition. You can work with 
parts in the following ways. 

Importing VAGen parts 

If you want to work with VisualAge Generator parts that are in an external 
source format, you can import them into VisualAge Generator Developer. You 
can import VAGen parts from an external source format file on the 
workstation. 

To import an external source format file, complete the following tasks: 

1 . From the VAGen Parts Browser, from the VAGen Parts menu, select 
Import/ExporHVAGen Import. 

2. On the Select a file to import window, specify the full path name for the 
external source format file you want to import. Then select OK. 

After you select a file to import, the VAGen Import window is opened. 

Exporting VAGen parts 

After you define and test a program and its associated parts, you can export a 
single part, all first found parts, or all the parts within a single program. You 
can export the parts and place them in an external source format file, which 
can then be imported by other developers who prepare and generate the parts 
for the run-time environment. They can prepare a single part or all the parts 
within a single program. 

You can export VAGen parts to an external source format file on the 
workstation. 

Alternatively, you can create a batch command to export the external source 
format of your parts. 

Manipulating VAGen parts 

VAGen parts include programs, functions, map groups, maps, records, tables, 
program specification blocks (PSBs), data items, generation options parts, 
linkage tables, resource associations parts, bind control parts, and link edit 
parts. You define each of these types of parts using the VisualAge Generator 
Developer editors. 

From the VAGen Parts Browser, you can select the applications and types of 
parts you want displayed in the browser. To change the parts listed in the 
browser, from the Part names field, specify the criteria to sort the list of parts 
in the browser. 
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Creating a new VAGen part 

To create a new VAGen part: 

1 . From the VisualAge Organizer window, select VAGen Parts ->New. 

2. In the New Part field, enter a valid part name. 

3. Select a part type. 

4. Select a valid application to add your VAGen part to. 

5. Select OK. 

Application 

Use the Application drop-down list to select the application to contain the 
newly defined parts. 

The drop-down list will contain only valid target applications for VAGen part 
types. 

Valid target applications must already contain the VAGen Part class of the 
selected type. 

If the target application does not contain the VAGen Part class, the application 
must meet the following preconditions: 

• The target application must be an open edition, and you must be a group 
member. 

Note: A scratch edition is not an open edition. You can add VAGen parts to 
application scratch editions, but only if the application already contains 
an extension of the VAGen Part class for the type of part you want to 
add. 

Creating VAGen parts 

To create a new part, use the New VAGen Part window. 

You can define the following types of parts in VisualAge Generator: 

• Program 

• Function 

• Map Group 

• Map 

• Record 

• Table 

• PSB 

• Data Item 

• Generation Options 

• Linkage Table 

• Resource Associations 

• Bind Control 

• Link Edit 
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Creating a new program 

To create a new program: 

1 . On the VAGen Parts Browser, select the VAGen Parts menu, then New. 
or 

From the Program Editor, select the File menu, then New. 

2. In the New Part field, enter a valid program name. 

3. Select Program as the part type. 

4. Select a valid application to add your program to. 

5. Select OK. The new part is displayed in the Program Editor. 

6. In the Program Editor, select the type for the program from the Program 
Type/Execution Mode drop-down list box on the tool bar. 

Program names: Use the following conventions when naming programs: 

• Maximum length: 7 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

• DBCS name: No 

• Set testpoints: Yes 

• The program name must be unique within a CICS execution system and 
within a target MVS load library 

• To avoid potential conflicts with the program names generated for the map 
groups, do not end the program name with FM or PI 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

• Part names cannot be COBOL reserved words. 

Application: Use the Application drop-down list to select the application to 
contain the newly defined parts. 

The drop-down list will contain only valid target applications for VAGen part 
types. 

Valid target applications must already contain the VAGen Part class of the 
selected type. 

If the target application does not contain the VAGen Part class, the application 
must meet the following preconditions: 

• The target application must be an open edition, and you must be a group 
member. 
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Note: A scratch edition is not an open edition. You can add VAGen parts to 
application scratch editions, but only if the application already contains 
an extension of the VAGen Part class for the type of part you want to 
add. 

Setting program preferences 

To set program preferences: 

1 . On the VAGen Parts Browser, select the Options menu, then Preferences. 

2. Select the Program page to set the available preferences. 

Creating a new function 

A function is a block of logic consisting of a set of statements surrounding a 
central operation. 

To create a new function: 

1 . From the VAGen Parts Browser, select the VAGen Parts menu, then New. 
or 

From the Function Editor, select the File menu, then New. 

2. In the New Part field, enter a valid function name. 

3. Select Function as the part type. 

4. Select a valid application to add your function to. 

5. Select OK. 

Function names: Use the following conventions when naming functions: 

• Maximum length: 18 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9), underscore (_), hyphen ( — ), or 
one of the valid national characters for your workstation 

• DBCS name: Yes, maximum length: 8 

• Set testpoints: Yes 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

To avoid aliases being assigned during COBOL generation, and to improve 
the readability of the generated COBOL program, use a name that meets the 
following COBOL naming conventions: 

• Do not use COBOL reserved words. 

• Do not use @, #, $, or _ characters. 

• Do not use DBCS names. 
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For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 

Defining a map group 

When you create a new map, you specify the name of its map group. An icon 
for the map group you choose is displayed in the Specifications section of the 
program diagram. If you want to see a list of maps in a map group that are 
using a particular device, you must first define the map group. To define a 
map group: 

1 . Open a program that uses a map from the map group you want to define. 

2. In the Program Editor, double-click on the Map Group part under 
Specifications. 

3. In the New Part application window, ensure that the part name and part 
type are correct, then select the name of the application you want to add 
the map group to. 

4. Select OK. 
Creating a new map 

1 . On the VAGen Parts Browser, select the VAGen Parts menu, then New. 
or 

In the Map Editor, select the File menu, then New. 

2. In the New Part field, enter a map group name and a map name 
separated by a space. The name you enter first is the map group name. 
The name you enter second is the map name. 

3. Select Map as the part type. 

4. Select a valid application to add your map to. 

5. Select OK. The new part is displayed in the Map Editor. 

Map group names: Use the following conventions when naming map 
groups: 

• Maximum length: 6 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

• DBCS name: No 

• Set testpoints: No 

• The map group name cannot have the same name as the map 

• The map group name cannot have the same name as another program in 
the MVS library or the same CICS system 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 
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Note: The following compatibility considerations exist for the naming of 
maps and map groups: 

IMS/VS All maps in a map group are generated in a single MFS 

message input description (MID) or message output 
description (MOD) per device. If you have a large map 
group, it can exceed the 32K size limit for MFS control 
blocks. For more information on estimating the size, 
refer to the Desigti Guide document. 

IMS BMP If you specify the MSP(MFS) or the MSP(ALL) 
generation option, the IMS/VS compatibility 
considerations apply. Otherwise, there are no 
compatibility considerations. 

Map names: When you name a map, you must precede the map name with 
a map group name followed by a space. 

Use the following conventions when naming maps: 

• Maximum length: 8 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9), or one of the valid national 
characters for your workstation 

• DBCS name: No 

• Set testpoints: Yes 

• The map name cannot have the same name as the map group 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

Note: The naming conventions for variable field names are the same as for 
data item names. 

Map group names: Use the following conventions when naming map groups: 

• Maximum length: 6 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

• DBCS name: No 

• Set testpoints: No 

• The map group name cannot have the same name as the map 

• The map group name cannot have the same name as another program in 
the MVS library or the same CICS system 
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The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

Note: The following compatibility considerations exist for the naming of 
maps and map groups: 

IMS/VS All maps in a map group are generated in a single MFS 

message input description (MID) or message output 
description (MOD) per device. If you have a large map 
group, it can exceed the 32K size limit for MFS control 
blocks. For more information on estimating the size, 
refer to the Design Guide document. 

IMS BMP If you specify the MSP(MFS) or the MSP(ALL) 
generation option, the IMS/VS compatibility 
considerations apply. Otherwise, there are no 
compatibility considerations. 

Data item names: Use the following conventions when naming data items: 

• Maximum length: 32 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9), underscore (_), hyphen (-), or 
one of the valid national characters for your workstation 

• DBCS name: Yes, Maximum length: 15 

• Set testpoints: No 

• An asterisk can be used as the data item name in any record or table 
structure. This type of data item is called a filler data item, which cannot be 
referenced by a program. The name acts as a place holder in a data 
structure 

• A data item name can be used only once within a single record or table 

• To avoid aliases being assigned during COBOL generation and to improve 
the readability of the generated COBOL program, use a name that meets 
the following COBOL naming conventions: 

- Use 30 characters or less in data item names. 

- Do not use DBCS names for data item names if your program contains 
SQL functions. 

- Do not use COBOL reserved words. 

- Do not use @, #, $, or _ characters. 

For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 
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The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

Data items in DL/I records name 

Data item names used in DL/I records are limited to 8 characters. They 
cannot be DBCS names or contain hyphens or underscores. If you want to use 
long names for data items in a DL/I record, define a redefined record for the 
DL/I segment and use long names for the fields in the redefined record. Use 
the DL/I segment definition only as the I/O object and in defining DL/I calls. 

For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 

Application: Use the Application drop-down list to select the application to 
contain the newly defined parts. 

The drop-down list will contain only valid target applications for VAGen part 
types. 

Valid target applications must already contain the VAGen Part class of the 
selected type. 

If the target application does not contain the VAGen Part class, the application 
must meet the following preconditions: 

• The target application must be an open edition, and you must be a group 
member. 

Note: A scratch edition is not an open edition. You can add VAGen parts to 
application scratch editions, but only if the application already contains 
an extension of the VAGen Part class for the type of part you want to 
add. 

Setting map preferences 

To set map preferences, on the VAGen Parts Browser, select the Options 
menu, then Preferences. Select Map to set the available options. 

Creating a new record 

A record is a collection of related data items treated as one unit. Records in 
VisualAge Generator are the information units that form a file or database. 

To create a new record: 

1 . From the VisualAge Organizer window, select VAGen Parts ->New. 
or 

From the Record Editor, select the File menu, then New. 
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2. In the New Part field, enter a valid part name. 

3. Select Record as the part type. 

4. Select a valid application to add your record to. 

5. Select OK. 

6. In the Record Editor, select the type for the record from the Record Type 
drop-down list box on the tool bar. 

7. Select a usage from the Default Usage list box. 

Record names: Use the following conventions when naming records: 

• Maximum length: 18 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9), underscore (_), hyphen ( — ), or 
one of the valid national characters for your workstation 

• DBCS name: Yes, maximum length: 8 

• Set testpoints: Yes 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

To avoid aliases being assigned during COBOL generation, and to improve 
the readability of the generated COBOL program, use a name that meets the 
following COBOL naming conventions: 

• Do not use COBOL reserved words. 

• Do not use @, #, $, or _ characters. 

• Do not use DBCS names. 

DL/I records name 

DL/I record names are limited to 8 characters. They cannot be DBCS names, 
nor can they contain hyphens or underscores. If you want to use long names 
for a DL/I record, define a redefined record for the DL/I record using long 
names in the redefined record. You can use the redefined record name 
everywhere in the program except as an I/O object name. 

SQL row records 

You cannot use filler data items in a SQL row record. Any data item named 
with an asterisk (*) is a filler item. 

For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 
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Application: Use the Application drop-down list to select the application to 
contain the newly defined parts. 

The drop-down list will contain only valid target applications for VAGen part 
types. 

Valid target applications must already contain the VAGen Part class of the 
selected type. 

If the target application does not contain the VAGen Part class, the application 
must meet the following preconditions: 

• The target application must be an open edition, and you must be a group 
member. 

Note: A scratch edition is not an open edition. You can add VAGen parts to 
application scratch editions, but only if the application already contains 
an extension of the VAGen Part class for the type of part you want to 
add. 

Creating a new table 

A table is a collection of related data items used in editing data entered by 
your user on a user interface such as a map or HTML page or in storing 
information for reference by a program when it runs. 

To create a new table: 

1 . From the VisualAge Organizer window, select VAGen Parts ->New. 
or 

From the Table Editor, select the File menu, then New. 

2. In the New Part field, enter a valid table name. 

3. Select Table as the part type. 

4. Select a valid application to add your table to. 

5. Select OK. 

6. In the Table Editor, select the type for the table from the Table Type 
drop-down list box on the tool bar. 

Table names: Use the following conventions when naming tables: 

• Maximum length: 7 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

• DBCS name: No. 

• Set testpoints: Yes 

• Table names cannot end with a 0 (zero) 

• The table name must be unique within a CICS execution system and within 
a target MVS load library 
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• To avoid potential conflicts with the program names generated for the map 
groups, do not end the table name with FM or PI 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

See the rules for the prefix for message tables. 

Message table prefixes: Use the following conventions when naming message 
table prefixes: 

• Maximum length: 4 

• First character: alphabetic (A-Z) 

• Other characters: alphanumeric (A-Z, 0-9) 

The message table prefix is specified in the Properties window in the Program 
Editor. 

A suffix is appended to the message table prefix to build the name of the user 
message table. The suffixes for the national languages supported by VisualAge 



Generator are: 


Code 


Language 


CHS 


Simplified Chinese 


CHT 


Traditional Chinese 


DES 


Swiss German 


DEU 


German 


ENP 


Uppercase English 


ENU 


US English 


ESP 


Spanish 


FRA 


French 


ITA 


Italian 


JPN 


Japanese 


KOR 


Korean 


PTB 


Brazilian Portuguese 



Note: Uppercase English is not supported by AIX, OS/2, Windows NT, 
HP-UX, SCO OpenServer, and Solaris. 

Creating a new PSB 

To create a new PSB: 

1 . From the VAGen Parts menu, select New 
or 

From the PSB Editor, select the File menu, then New. 

2. In the New Part field, enter a valid PSB name. 



Chapter 8. Managing VAGen parts in VisualAge Smalltalk 189 



3. Select PSB as the part type. 

4. Select a valid application for your function. 

5. Select OK. 

PSB names: Use the following conventions when naming PSBs: 

• Maximum length: 8 

• First character: alphabetic (A-Z) or one of the valid national characters for 
your workstation 

• Other characters: alphanumeric (A-Z, 0-9) or one of the valid national 
characters for your workstation 

• DBCS name: No 

• Set testpoints: No 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 

To avoid aliases being assigned during COBOL generation, and to improve 
the readability of the generated COBOL program, use a name that meets the 
following COBOL naming conventions: 

• Do not use COBOL reserved words. 

• Do not use @, #, $, or _ characters. 

For information about using national characters or DBCS naming conventions, 
see "Appendix A. DBCS name characteristics" on page 353. 

Application: Use the Application drop-down list to select the application to 
contain the newly defined parts. 

The drop-down list will contain only valid target applications for VAGen part 
types. 

Valid target applications must already contain the VAGen Part class of the 
selected type. 

If the target application does not contain the VAGen Part class, the application 
must meet the following preconditions: 

• The target application must be an open edition, and you must be a group 
member. 

Note: A scratch edition is not an open edition. You can add VAGen parts to 
application scratch editions, but only if the application already contains 
an extension of the VAGen Part class for the type of part you want to 
add. 
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Defining a shared data item 

You can define shared data items using the Data Item Editor. 

Steps for defining a shared data item 

1 . To open a data item, do one of the following: 

• From the VisualAge Organizer window, select VAGen Parts ->Open to 
open an existing shared data item. 

or 

From the Data Item Editor, select the File menu, then Open to open an 
existing shared data item in the Data Item Editor. 

• From the VisualAge Organizer window, select VAGen Parts ->New to 
define a shared data item. On the New VAGen Part window, select the 
Data Item button, enter a name for the data item, and select an 
application to attach your new data item to. When you select Save from 
the File menu, the Data Item Editor is opened. 

or 

From the Data Item Editor, select the File menu, then New to define a 
shared data item in the Data Item Editor. 

• From the VAGen Part or the File menu, select New to define a new 
shared data item. 

2. In the Data Item Editor, you can specify the following types of 
information: 

• The data type 

• The length of the data item, either when displayed or when stored 
internally 

• If it is a numeric data item, the number of decimal places 

• A description of the data item 

3. To define default map edit characteristics for a shared data item in the 
Data Item Editor, from the Define menu, select Default Map Properties. 

4. To define UI properties for a shared data item in the Data Item Editor, 
from the Define menu, select UI Properties. 

5. After you finish defining or editing the shared data item, select Save from 
the File menu in the Data Item Editor to save the changes. Then close the 
Data Item Editor. 

For an existing shared data item, you can create a copy of the shared data 
item with a new name. From the File menu, select Save as. 

Setting generation options from the UI 

You can set generation options from the user interface (UI). Each target 
environment has a set of generation options available from the generation 
options notebooks. You are not required to specify values for the generation 
options because default values are provided. 
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When NOOVERRIDE is specified for an option in the generation options 
defaults file, the field corresponding to that option is not available and the 
value defined in the default file is displayed. For details, refer to "Establishing 
default generation options" in the VisualAge Generator Generation Guide. 

Setting generation preferences 

To set default generation preferences: 

1 . From the VisualAge Organizer window, select VAGen Parts^Parts 
Browser. 

2. From the VAGen Parts Browser, select Options-* Preferences 

3. On the VisualAge Generator Preferences navigation pane, select 
Generation. 

4. For code generated for the client, in the Client group box, select a 
generation options part. 

If you want code to be generated automatically when a part is saved, 
check the Generate code when saved box. 

5. For code generated for the server, in the Server group box, select a 
generation options part. 

6. You can generate server programs in batch by specifying commands in a 
generation options file. When you use the generation UI for batch 
generation, a command file is created for you that contains one of the 
following commands: 

HPTCMD Select this command if you are generating on the local 
machine. 

CALL EFKREQ 

Select this command if you are generating on a remote 
(Generation Server) machine. 

User specified Select this command if you want to specify the name of 
the program that will control generation of the selected 
parts. The program you specify must use HPTCMD or 
CALL EFKREQ commands directly or indirectly. 

Creating a linkage table 

For information on creating a linkage table, refer to the appendix on linkage 
tables in the VisualAge Generator Client/Server Communications Guide. 

Creating a resource associations part 

To create a resource associations part, take the following steps: 

1 . Create a new VAGen part. 

2. For the part type, select Others and then Resource Associations. 

3. Enter the name of your resource associations part and select OK. 
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When you generate a COBOL or CICS/6000 application that uses serial, 
relative, or indexed files, or printer maps, you can use a resource associations 
part to associate target-system dependent file characteristics, including the file 
type and the system file or resource name, with the file name specified in the 
VAGen record definition. 

Refer to the VisualAge Generator Generation Gwfdedocument for information 
about resource association. 

Creating a bind control part 

For information on creating a bind control part, refer to the chapter on bind 
control parts in the VisualAge Generator Generation Guide. 

Creating a link edit part 

For information on creating a link edit part, refer to the chapter on link edit 
parts in the VisualAge Generator Generation Guide. 



Versioning and releasing 

When you version a class or an application, you prevent further changes to 
the parts and classes it contains. Version names are usually followed by a 
version number. Unversioned class names are preceded by a right angle 
bracket (>) and followed by a date and time stamp. Unversioned applications 
names are preceded by an open folder icon and followed by a date and time 
stamp. 

To version a class: 

1 . From the VisualAge Organizer window Parts pane, select an open edition 
of a class. 

2. From the Parts menu, select Version. 
To release a class: 

1 . From the VisualAge Organizer window Parts pane, select a versioned 
edition of a class. 

2. From the Parts menu, select Release. 
To version an application: 

1 . From the VisualAge Organizer window Applications pane, select an open 
edition. 

2. From the Applications menu, select Version. 
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Chapter 9. Developing VAGen parts 



Using the VAGen Parts Browser 

After you have created or loaded applications to store your VAGen parts, use 
the VAGen Parts Browser to create new parts and customize your view of 
VAGen parts loaded into your image. 

To open the VAGen Parts Browser, from the VisualAge Organizer window, 
select VAGen Parts-* VAGen Parts Browser. 

To create a new part from the VAGen Parts Browser, select VAGen 
Parts-»New. For more information about creating new parts, see "Creating 
VAGen parts" on page 180. 

Reordering columns 

To reorder columns in the VAGen parts list: 

1 . From the VAGen Parts Browser, from the VAGen Parts menu, select View, 
then Reorder Columns. 

2. In the Reorder Columns window, drag and drop column heading names 
where you want them. The heading name at the top of the list is the first 
column displayed in the VAGen parts list. Other heading names above the 
Hidden Columns line are displayed consecutively from left to right. You 
can also drag the Hidden Columns line to a new location. 

3. Select Apply, to accept and view your changes or OK to accept your 
changes and close the Reorder Columns window. 

Hiding columns 

For faster display time in the VAGen Parts Browser, consider hiding columns 
you don't need to see. Hiding Description, or Part Type and Subtype can 
noticeably improve performance. 

Customizing the status bar 

To change the information displayed in the status bar area: 

1 . From the VAGen Parts Browser, from the VAGen Parts menu, select View, 
then Reorder Status Bar Text. 

2. In the Reorder Status Bar Text window, drag and drop column heading 
names where you want them. The first heading name in the list is the first 
piece of information displayed in the status bar. Information under other 
heading names above the Hidden Columns line is displayed consecutively 
from right to left. 

To hide the status bar, drag the Hidden Columns line to the top of the list. 
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3. Select Apply, to accept and view your changes or OK to accept your 
changes and close the Reorder Status Bar Text window. 

Sorting information 

There are two ways to sort information displayed in the VAGen Parts 
Browser. 

• In the VAGen parts list, click on a column heading to sort the parts by that 
column. For example, if you click on the Part Name column heading, the 
parts will be reordered alphabetically by part name. 

• To sort using menus: 

1 . From the VAGen Parts menu, select View-»Sort by. 

2. From any of the Sort by menu items select a type of sort. 

Note: Using this method, you can sort on columns that are not 

displayed in the VAGen parts list, but you might find it more 
helpful to display the column you are sorting on. 

Note: Selecting the same sort order again (or clicking on the column twice) 

reverses the sort order. For instance, if you select Sort by Name, the list 
is displayed in alphabetically ascending order (a-z). If you select it 
again, the list will be sorted in alphabetically descending order (z-a). 

Filtering information 

To filter the parts displayed in the VAGen Parts pane, select items from the 
Packages / Applications and Types panes or type a pattern in the Part Names 
filter. Only parts matching the filter criteria are displayed. 

If you use the Show Names Filter from the References window, select items 
from the Packages / Applications or Types panes or type a pattern in the Part 
Names filter to change the scope of your search for part references. When 
changes to the filter are made, the references search is performed again. 

Saving your settings as defaults 

To save your VAGen Parts Browser settings as defaults, from the Options 
menu, select Save Settings as Defaults to save the window size, sort order, 
columns shown, column sizes, and status bar text displayed in the VAGen 
Parts Browser. 

The saved values will be used when opening a new VAGen Parts Browser. 

Enabling the V3 to V4 migration tool 

You can enable the migration tool using the command line or the product 
icon. 

To start the 3.x Migrator tool, use these steps: 
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1 . From the VisualAge Organizer window, select VAGen Parts-»Parts 
Browser. 

2. From the VAGen Parts Browser, select Tools-»Migration->V3 to V4 
Migration. 



Programs 

A VAGen program contains elements that define the structure of the program. 
Functions and flow statement definitions implement business logic through 
statements that handle data when the program runs. 

Think of a VisualAge Generator program as a collection of modular pieces, 
defined primarily by the different types of input and output (I/O) required. 
Each I/O operation requires a separate logic block, and additional supporting 
business logic can be included in that block. 

Program logic: 

• Displays panels and prints reports 

• Accesses files and databases 

• Moves data among records, maps, files and databases 

• Performs arithmetic calculations and other types of operations 

I/O options and I/O objects are accessed by functions to perform these tasks. 

A sequence of main functions defines the default flow of the main program 
logic. To modify the default flow of the logic, you can define flow statements 
for each of the main functions. Flow statements are stored with the program; 
they are not part of the function. 

Defining a program 

When you define a program, you are actually defining functions, maps, 
records, and other types of parts. Depending on the type of program you are 
building, you might not need to do all of the following tasks. If you are 
creating a new program, the following steps are arranged in logical order. 

To define a program: 

1 . Create a new program 

2. Define the Program Type/Execution Mode. 

3. Define program properties 

4. Define program specifications 

5. Define additional records and tables 

6. Define called parameters 

7. Define program logic 

8. Define a program prolog 
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Selecting a program type 

To select a program type: 

1 . In the Program Editor, select one of the Program Type / Execution Mode 

menu choices: 

Main Transaction - Nonsegmented 

Choose the Main Transaction - Nonsegmented Program Type / Execution 
Mode when you want I/O locks and database and file positions maintained 
across a CONVERSE. When you select Main transaction - Nonsegmented, a 
CONVERSE does not mark the end of a unit of work. 

You should choose a Main Transaction type when you want to start the 
program by a transfer from the system or another program and you want 
your user to interact with the program using maps. 

Main Transaction - Segmented 

Choose the Main Transaction - Segmented Program Type / Execution Mode 
when you want each write to the terminal (CONVERSE or XFER with map) to 
be the end of a unit of work. 

You should choose a Main Transaction type when you want to start the 
program by a transfer from the system or another program and you want 
your user to interact with the program using maps. 

Main Transaction - Single Segment 

Choose the Main Transaction - Single Segment Program Type / Execution 
Mode when you want to stop the program after processing a single input 
from the terminal or when control transfers to another program. When you 
select Main Transaction - Single Segment, you must use the XFER statement 
with a map and a first map for all terminal I/O operations. The CONVERSE 
I/O option is not allowed in Main Transaction - Single Segment programs. 

You should choose a Main Transaction type when you want to start the 
program by a transfer from the system or another program and you want 
your user to interact with the program using maps. 

Web Transaction 

Choose the Web Transaction Program Type / Execution Mode when you want 
to start the program by a transfer from the system or another program and 
you want your user to interact with the program through a Web browser 
using HTML pages and forms. You should choose Web Transaction when you 
want to develop a Web application. 

The VisualAge Generator Web Transaction programming model enables you 
to develop 4GL-based business systems that use a Web browser to display the 
user interface and generated run-time programs for business logic and 
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database processing. The Web Transaction programming model is related to 
the model used for Text User Interface (TUI) programming in VisualAge 
Generator. Similar component roles exist, and the method of interacting with 
your user is based on a similar use of either the 4GL CONVERSE processing 
option or XFER single segment transfer technique. Using a Web Transaction 
program, you can define a web application as a single threaded program 
which interacts with your user by sending business data directly to a browser 
through the use of the User Interface Record data definition and either the 
CONVERSE or XFER language verb. 

The execution mode of a Web Transaction program is like a Main transaction - 
Segmented program in that each write to the back end system or web server 
is the end of a unit of work. Unlike Main Transactions, where the generated 
user interface closely resembles the user interface you see in the VisualAge 
Generator Map editor, the outputs from generating a Web Transaction 
program include a Java bean with user interface data. The generated UI 
record bean contains data definitions, edits, and default HTML. User interface 
developers can customize the HTML page presented to your user through a 
Web browser by modifying or adding new information to the contents of the 
generated UI record bean. 

The process of developing and implementing a Web application using the 
Web Transaction programming model includes creating Web Transaction 
programs and UI records, and using such elements generated by or provided 
with VisualAge Generator as UI record beans, resource bundles, JSPs, the 
GatewayServlet and Session ID Manager. For information on developing and 
implementing Web Transaction programs, see Building e-Business Transaction 
Systems with VisualAge Generator: Using the Web-Transaction Programming Model 
(SG24-5636-00). 

Called Transaction 

Choose the Called Transaction Program Type / Execution Mode when you 
want to call the program from another program and you want your user to 
interact with the program using maps. When you select Called transaction, 
the called program can pass and reset parameters. 

Main Batch 

Choose the Main Batch Program Type / Execution Mode when you want to 
start the program by a transfer from the system or another program and you 
do not want your user to interact with the program using maps. 

Called Batch 

Choose the Called Batch Program Type / Execution Mode when you want to 
call the program from another program and you do not want your user to 
interact with the program using maps. When you select Called Batch, the 
called program can pass and reset parameters. You should choose Called 
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Batch for server programs called from remote clients and for subroutine 
programs that do not converse or display 3270 maps. 

Defining program properties 

To define program properties: 

1 . In the Program Editor, select the Define menu, then Properties. 

2. On the Program Properties window, enter appropriate values for your 
program and select OK. 

Defining specifications 

To define specifications for your program: 

1 . In the Program Editor, click mouse button 2 on the Specifications symbol 
in the diagram and select the type of part you want to add: Working 
Storage, PSB, Firstmap, Map Group, or Help Map Group. 

2. Type a valid part name in the Part name field and select OK. 

3. In the Program Editor, double-click on the new part, to display it in the 
appropriate editor. 

4. Make any changes you need to and save the part. 

You can also replace, delete, or edit parts in this section by clicking on them 
with mouse button 2 and selecting the appropriate choice from the context 
menu. 

Defining tables and additional records 

In the Specifications section of the program diagram, you can define Tables 
and Additional Records. 

An additional record is: 

• A record that is not the working storage record defined in the Program 
Editor. 

• A record that does not appear in the called parameter list 

• A record that is not displayed as an I/O object for a function in the 
program 

Before you start defining additional tables /records, expand the Tables and 
Additional Records section to see a list of parts that are already defined. 

To expand the list, click on the gray square to the left of the Tables and 
Additional Records symbol. 

To add an additional record or table: 

1 . Click mouse button 2 on the Tables and Additional Records symbol and 
select Insert Table/Record from the context menu. 

2. On the Insert Table/Record window, select a part type and a part name. 
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3. Select OK. 

4. If you selected a part that is not already defined in the library double-click 
on it in the Program Editor to finish defining it. 

You can also replace, delete, or edit parts in this section by clicking on them 
with mouse button 2 and selecting the appropriate choice from the context 
menu. 

Note: Tables that are referenced in program logic or used as map edit 
routines must be specified in the Tables and Additional Records. 

Defining called parameters 

In the Specifications section of the program diagram, you can define Called 
Parameters for Called Transactions or Called Batches. The Called Parameters 
symbol is only displayed in the Specifications section for programs of these 
two types. To define a called parameter: 

1 . Click mouse button 2 on the Called Parameters symbol and select Insert 
Parameter from the context menu. 

2. On the Insert Parameter window, select a part type and a part name. 

3. Select OK. 

4. If you selected a part that is not already defined in the library, double-click 
on it in the Program Editor to finish defining it. 

You can also replace, delete, or edit parts in this section by clicking on them 
with mouse button 2 and selecting the appropriate choice from the context 
menu. 

Defining program logic 

To define program logic: 

1 . Add a main function to the program, by clicking mouse button 2 on the 
Structure Diagram symbol and selecting Insert Main Function. 

2. On the Insert Main Function window, specify a name for the function; 
then select OK. 

3. To further define the main function, double-click on the main function 
symbol. 

4. On the New Part Package /Application window, select a 
package/application to contain the function and select OK to display the 
Function Editor. 

5. In the Function Editor, use Statement Templates to define logic 
statements. 

6. (Optional) To define flow statements for the program, in the Program 
Editor, click mouse button 2 on a main function. From the context menu 
select Flow Statements. 



Chapter 9. Developing VAGen parts 201 



Note: Flow statements are associated with the main function, but stored 
with the program. 

Defining a program prolog 

Describe and comment your program in a prolog. To add a prolog to your 
program: 

1 . In the white space outside the program diagram in Program Editor, click 
with mouse button 2 and select Prolog from the context menu. 

or 

In the Program Editor, select the Define menu, then Prolog. 

2. In the Prolog window, type your description. To use editing functions in 
the Prolog window, click with mouse button 2 in the white space and 
select a function from the context menu. 

3. Select OK to save your description and close the window. 
Working with program diagrams 

Collapsing/Expanding symbols 

Symbols with a + (collapsed) or - (expanded) to the left of the symbol have a 
subtree of symbols that can be hidden or shown as desired by clicking on the 
+ or -. The subtree for a symbol will be expanded one level by clicking on the 
+. Use the context menu to expand the whole subtree with a single action. 

You can set your Program preferences to control the initial display of the 
structure diagram section of the program diagram. The default is to initially 
show only the main functions. 

Note: It is recommended, especially for large program diagrams, to leave the 
initial display set for main functions, and then expand symbols only as 
you need to work with that portion of the logic. Only the parts 
required to display the symbols are read from the library, so additional 
reading of parts is delayed until you start expanding symbols. 
However, once you expand a symbol, you cannot buy back the memory 
required for the subtree by collapsing the symbol. 

Editing parts 

You can open the editor for any VisualAge Generator part displayed on the 
program diagram by double-clicking the symbol for the part. "Edit part" is 
available from the context menu for a symbol and does the same thing as the 
double-click. If the part has not yet been defined, the New Part 
Package/ Application window is displayed, which enables you to create the 
part and then open the editor. 
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Managing lists 

The "Tables and Additional Records", "Called Parameters", and "Structure 
Diagram" symbols represent a list of parts, which are shown as the children of 
the Descriptor symbol. You can insert, delete, and move these parts within 
each list. 

All "Insert" actions will add the new part AFTER the symbol for which you 
perform the "Insert" action. To insert a new part as the first part in the list, 
invoke the context menu on the Descriptor symbol. Thus, if you want to insert 
a new main function as the first function to be executed, invoke the context 
menu on the "Structure Diagram" symbol and select "Insert Main Function". 

You can reorder the parts in the list by dragging and dropping one or more 
parts to a new position in the list. As with "Insert" actions, you should drop 
the dragged symbols onto the symbol AFTER which you want the dropped 
symbols to be placed. 

Editing tasks 

While editing text, you can perform the following tasks: 
Insert a line 

Move the cursor to the end of the line and press Enter. 
Split a line 

Move the cursor to the position where you want to split the line and 
press Enter. 

Join two lines 

Move the cursor to the end of the first line to be joined and press 
Delete. 

Select text 

Move the cursor to the beginning of the text you want to select. Press 
and hold mouse button 1. Drag the mouse to the end of the text you 
want to select. Release mouse button 1. 

Note: When text is selected, pressing any character key replaces the 
selected text with the new character. 



Functions 

A function is built around a specific operation called an I/O option. An I/O 
option is the I/O operation the function performs, such as displaying a map 
or gaining access to a record. 

The map or record you specify as the object of the I/O operation is called the 
I/O object. You can specify only one I/O object for each function. 
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Add statements before or after the I/O object and I/O option to complete 
your function. One of the easiest ways to add statements is using the 
Statements Templates editor.For specific instructions, see the section on using 
the Statement Templates editor. 

For more information on transferring control between programs, see 
"Appendix E. Program Control Linkage Conventions" on page 407. 

Defining I/O options and I/O objects 

1 . In the Function Editor select an I/O Option from the first drop-down list 
to the right of the tool bar icons. 

2. (Optional) If you need to use an I/O Object, select one from the second 
drop-down list to the right of the tool bar icons. 

Note: The I/O object list is not available for EXECUTE I/O options. 

• If you select an SQL row record as a I/O object, from the Define menu, 
select SQL statement to define the SQL statements for this function. If 
you have not already set your SQL preferences, ensure that the default 
settings are acceptable. 

• If you want to use a segment in a DL/I database as a I/O object, you 
must first define the segment as a PCB in a PSB. Then, from the 
Function Editor you can select Define then DL/I Call to specify the 
DL/I call as a function object. If you have not already set your DL/I 
preferences, ensure that the default settings are acceptable. 

Defining function properties 

To define function properties: 

1 . From the Define menu, select Properties. 

2. If you specified a record as an I/O option, type the name of a part or 
select a part from the Error routine list box to specify an Error routine. 

3. In the Description field, type a 1-30 character description of the function. 

4. (Optional) You can select the Default collapse check box to set the default 
display of the function, as it appears in the Program Editor, to collapsed. 
This means that any parts under the function in the program hierarchy are 
hidden, unless you expand the Structure Diagram. 

5. Select OK. 
Error routine 

If you want the function you are working with to have an error routine, select 
an error routine from the drop-down list or type the 1- to 18-character name 
of the error routine in the Error routine field. 

If you specify a function, the function name cannot be the same as the 
function being edited. 



204 VisualAge Generator: User's Guide 



If you do not specify an error routine, a program ends when an error occurs 
with a message describing the error condition. This includes standard 
situations such as the end-of-file (EOF) condition. 

You cannot specify error routines for functions with map I/O objects or for 
EXECUTE functions. Display or printer errors cause the program to end. 

The error routine can be any of the following: 

• A valid special function word EZERTN, EZEFLO, or EZECLOS. 

• The name of a function 

The function must be defined as a main function in the same program as 
the function used as an error routine. 

If the error routine is a function, then control is transferred to that function 
when an error occurs. Control returns to the statement following the I/O 
option after the error routine ends. 

You can test error codes returned by the system using the TEST, WHILE, and 
IF statements. 

Defining logic 

To define logic for your part, do any of the following: 

• Type statements directly into the statements area in the editor. You can use 
the standard editing tasks to update the statements. 

• Use the Statement Templates window to add statements. To use the 
Statement Templates window: 

- From the Tools menu, select Statement Templates. 

- To view lists of statements, EZE words, or service routines that you can 
paste into the statements area, select the type of statement you want to 
work with from the Categories list box. 

• To verify that the statements you added are valid, from the Tools menu, 
select Validate or Validate and Format. 

If an error is identified during validation, the Validation Errors window is 
displayed. Correct any errors displayed in this window before you save or 
the part or close the editor. 

For more information on specific language elements, refer to the online help 

or the VisualAge Generator Programmer's Reference. 

For more information on transferring control between programs, see 
"Appendix E. Program Control Linkage Conventions" on page 407. 
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Editing tasks 

While editing text, you can perform the following tasks: 
Insert a line 

Move the cursor to the end of the line and press Enter. 
Split a line 

Move the cursor to the position where you want to split the line and 
press Enter. 

Join two lines 

Move the cursor to the end of the first line to be joined and press 
Delete. 

Select text 

Move the cursor to the beginning of the text you want to select. Press 
and hold mouse button 1. Drag the mouse to the end of the text you 
want to select. Release mouse button 1. 

Note: When text is selected, pressing any character key replaces the 
selected text with the new character. 



Records 

A record or multiple records are individually accessible units of storage in a 
file or database. Records can also be used as temporary working storage when 
a program runs. A record consists of: 

• A specific record organization 

The record organization indicates both the structure of the file or database 
containing the collection of records and how to gain access to the record. 
You can choose from the following types of organizations: 

- DL/I segment 

- Indexed 

- Redefined 

- Relative 

- Serial 

- SQL row 

- User Interface 

- Working storage 

• A list of data items 

Defining a record 

If you are defining a new record, the following tasks are arranged in logical 
order 

1 . Create a new record 

2. Make a selection from the Record Type list box. 

3. Make a selection from the Default Usage list box. 

4. Define record properties 
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5. Define record prolog 

Define record properties 

From the Define menu in the Record Editor, select Properties to define or 
change record properties. Working storage records do not have properties. 
Additional information is available for each properties window when you 
select the window by name in the navigation frame of the online help. 

If you are working with a UI record, additional properties may be defined on 
the Record Data Item UI Properties window. To access the Record Data Item 
UI Properties window: 

1 . In the UI Properties column, select the UI Properties field for the data item 
you want to define. 

2. Select the pushbutton that appears beside the field. 

You can select Record Data Item UI Properties in the navigation frame of the 
online help for more information. 

Define record prolog 

To provide a record description, select Prolog from the Define menu in the 
Record Editor. 

Working with substructured data items 

In the editor, you can move data items between structures and alter the 
parent /child relationship of substructured data items by selecting a data item 
and dragging it to a new position in the list of data items. 

To move a substructured data item between structures and maintain the item 
at the same level, select the item and drag it to a new position in the list. You 
can move only one item at a time. However, if you select an item with 
children, the children are moved with the data item. You cannot move an item 
within its own structure. 

To move a substructured data item between structures and change the item's 
level, select the item, press the Alt key, and drag the item to a new position in 
the list. This enables you to move the data item to another structure as a child 
in the structure. 

Editing records 

To edit an existing record, do one of the following: 

• From the File menu within the Record Editor, select Open. 

• From the Parts Browser, select Open from the VAGen Parts menu. 

To select an individual data item, click on the item with mouse button 1. 
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To select multiple data items in a record, click on the first data item with 
mouse button 1, then press and hold the Shift key and click on the last data 
item with mouse button 1. 

You can add and modify data items in the Record Editor. Select a data item 
using the mouse and press the mouse button 2 to display the context menu of 
available actions for the selected data item. The context menu varies 
depending on the record type, number of data items selected and data item 

type- 
Some data item manipulation can be performed from choices in the Edit 
menu, but all available data item actions are provided by the context menu. 
Use the context menu to create Level 77 data items and add substructured 
data items. 

To validate and correct structural errors in the record, select Validate Data 
Structure from the Tools menu. Validation finds: 

• Data items whose types or lengths need to be changed based on the 
Substructure or Occurs values for those data items 

• Duplicate data item names 

When you close the Record Editor, you will be prompted to save your 
changes. If you defined new shared data items, you will be prompted to 
create and save these data items. 

Inserting, moving, and deleting data items 

You can insert a data item into the list by selecting an item in the list and 
choosing Insert before or Insert after from the Edit menu. You can also 
choose Insert Parent or Insert Substructure if your record is not an SQL Row 
record. 

Note: If you select Insert After and have not selected an entry in the list, the 
item is inserted at the end of the list. If you select Insert Before and 
have not selected an entry in the list, the item is inserted at the 
beginning of the list. If you do not have an entry in the list, you can 
still select Insert Before or Insert After from the Edit menu. 

You can Copy and Paste an item from another record or table to insert a data 
item. 

You can move a data item by selecting it and dragging it to a new position in 
the list. You can also use Cut and Paste to move a data item. 

To delete a data item, select the item and choose Delete from the Edit menu. 
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Working with shared data item definitions 

You can view and update a shared data item by selecting the data item, 
pressing mouse button 2, and selecting Edit part from the context menu. If the 
selected data item is nonshared, Edit part is not available. 

Creating a Ul record from a map 

This feature is available from the Organizer (VisualAge Generator on 
Smalltalk only) and the Parts Browser from the VAGen Parts pulldown as 
VAGen Parts ■* Create UI Record from Map. 

To create a corresponding working storage record, change the record type 
from UI to working storage. When you change the record type from UI 
record, all Ul-record-related data is removed. 

Creating core data item information 

For core data item information, local data items are created based on variable 
field data. Table 2 on page 57 shows the relationship. 



Table 10. How variable map field properties are converted to core data item properties 



Map data 


UI record data 
item 


Comment 


map field 
name 


data item 
name 


Unnamed map field names become filler items 
(name='*') in the UI record with an UI type of NONE. 
Map edits are not converted for unnamed map fields 
because filler items do not have UI properties. Map 
fields named EZEMSG is changed to data items named 
EZMSG. There is at most one EZEMSG variable field 
per record. 


map type 


data item type 


Since there are fewer map types, the resulting data item 
types are limited to Char, DBCS, Mixed and Num. 
Variable fields with Hex edit selected results in a Char 
data item. Hex edit is not supported for UI properties. 


map 

description 


data item 
description 




map length 


data item 
bytes 


The maximum bytes /length for numeric data items is 
18. If a numeric map field has a length greater than 18, 
the data item bytes /length is set to 18. 


map 
decimals 


data item 
decimals for 
numeric fields 





Creating record data item information 

For record data item information, the data item level defaults to 3. The UI 
type defaults to Input / Output except for filler items and data items named 
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EZMSG. Filler items must have a UI type of None with no UI properties. The 
UI type for data items named EZMSG is set to Output. 

For record data item information, local data items are created based on 
variable field data as shown in Table 3 on page 58. 



Table 11. How variable map field properties are converted to record data item 
properties 



Map data 


UI record data 


Comments 


map field 
array size 


data item 
occurs 


If a map field is not an array, the data item occurs 
defaults to 1. 


map field 
edit order 


data item edit 
order 


Only Input or Input/Output data items have an edit 
order value. Filler data items and Output data items 
have an input edit order of 0. For maps, all variable 
fields have an edit order assigned to it. 


map field 
name 


data item UI 
label 


The UI label for filler data items is blank. 



Removing EZMSG form the input edit order list may cause the input edit 
order value for other data items to change. Data items with an input edit 
order greater than the edit order of the EZEMSG variable field, from which 
the EZMSG data item was created, will have its input edit order value 
decreased by 1. 



Creating general UI edits 

Table 12. How general map edits are converted to general UI edits 



Map edit 


Data item edit 


Comments 


Check SO /SI space 


Check SO /SI space 


Convert as is. Check SO/SI 
should be set only for mixed 
data items. 


Edit routine 


Edit function 


If the edit routine is actually an 
edit table, it is up to you to 
make this change. 


Fill character 


Fill character 


A fill character of null is not 
supported for UI properties. A 
null fill character is converted to 
a space. 


Date edit mask 


Date 


If a date edit mask is defined, 
the data item date flag is set. 
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Table 12. How general map edits are converted to general ill edits (continued) 



Map edit 


Data item edit 


Comments 


Fold 


Fold 


If Variable field folding is 
selected from the Map 
Properties, the data item fold 
flag is set for all Char and Mixed 
Input/ Output data items that are 

L jr il TTT J T"" 1 J * 

created for the Ul record. Fold is 
valid for Char and Mixed data 
items. 


Input required 


Input required 


Convert as is. 


Minimum input 


Minimum input 


Convert as is. 


Edit routine message 
number 


Edit function message 
key 


Convert number to string. A 
message number of 0 results in a 
message key of blank. If the edit 
routine message number is 
actually an edit table message 
key the user has to make this 
change. 


Minimum input message 
number 


Minimum input 
required message key 


Input required message 
number 


Input required message 
key 


Data type message 
number 


Data type message key 



Creating numeric Ul edits 

Table 13. How numeric map edits are converted to numeric Ul edits 



Map edit 


Data item edit 


Comments 


Currency 


Currency 


Numeric map edits are converted only 
for numeric map fields. 


Separator 


Separator 


Minimum value 


Minimum value 


Maximum value 


Maximum value 


Sign 


Sign 


Zero edit 


Zero edit 


Numeric range 
message number 


Numeric range 
message key 


Convert number to string. A message 
number of 0 results in a message key of 
blank. Converted only for numeric fields. 



Tables 

A table is a collection of related data items structured as a two-dimensional 
array of rows and columns. The columns of the array are individually 
specified data items. 
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You can use a table name as the edit routine that supplies edit characteristics 
for a variable field on a map. The table is then used for checking map field 
input when the program runs. When data entered by the program user fails a 
table edit check, an error message is displayed. You can define the following 
types of tables for map editing: 

• Match valid 

• Match invalid 

• Range match valid 

You can define reference tables that a program uses when it runs. Visual Age 
Generator statements can be used to search and retrieve data from a reference 
table. You can use the same three types of tables as reference tables that you 
used for map editing. In addition, you can use the following types of tables 
exclusively for reference: 

• Unspecified 

• Message 

Defining a table 

If you are creating a new table, the following tasks are arranged in logical 
order. 

Creating a new message table 

You can create a new message table in the Table Editor. 

To create a new message table: 

1 . Create a two column table. 

2. Define the table type and column types according to your application: 

• For Web Transaction programs: 

- The table type can be Message table type or Unspecified table type 

- Either column can be character or mixed type. 

• For other programs: 

- The table type must be Message table type: 

- Column one must be numeric type. Column two can be either 
character or mixed type. 

3. Fill out the table with message Keys in column one and Messages in 
column two. 

Define table properties 

From the Define menu within the Table Editor, select Properties to define or 
change table properties. 

Define table contents 

To define the table's contents, select Table Contents from the Define menu. 
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Inserting, moving, and deleting data items 

You can insert a data item into the list by selecting an item in the list and 
choosing Insert before or Insert after from the Edit menu. You can also 
choose Insert Parent or Insert Substructure if your record is not an SQL Row 
record. 

Note: If you select Insert After and have not selected an entry in the list, the 
item is inserted at the end of the list. If you select Insert Before and 
have not selected an entry in the list, the item is inserted at the 
beginning of the list. If you do not have an entry in the list, you can 
still select Insert Before or Insert After from the Edit menu. 

You can Copy and Paste an item from another record or table to insert a data 
item. 

You can move a data item by selecting it and dragging it to a new position in 
the list. You can also use Cut and Paste to move a data item. 

To delete a data item, select the item and choose Delete from the Edit menu. 

Working with substructured data items 

In the editor, you can move data items between structures and alter the 
parent / child relationship of substructured data items by selecting a data item 
and dragging it to a new position in the list of data items. 

To move a substructured data item between structures and maintain the item 
at the same level, select the item and drag it to a new position in the list. You 
can move only one item at a time. However, if you select an item with 
children, the children are moved with the data item. You cannot move an item 
within its own structure. 

To move a substructured data item between structures and change the item's 
level, select the item, press the Alt key, and drag the item to a new position in 
the list. This enables you to move the data item to another structure as a child 
in the structure. 

Working with shared data item definitions 

You can view and update a shared data item by selecting the data item, 
pressing mouse button 2, and selecting Edit part from the context menu. If the 
selected data item is nonshared, Edit part is not available. 
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PCB restrictions 

Table 14. Restrictions for inserting PCBs into a PSB list 



PCB Type 


Restrictions for PCB types in a PSB 


TP 


Must come before all DB and all GSAM 


DB 


Must come after all TP and before all GSAM 


Segment 


Must come after a DB or between Segments 


GSAM 


Must come after all DB 



PSBs 

A program specification block (PSB) is a formal DL/I description of the 
hierarchical database structures that a program can gain access to. Visual Age 
Generator Developer supports the definition of a part in the library that 
contains a subset of the information in the DL/I PSB. The PSB definition 
describes the hierarchical relationship between types of segments. 

A PSB is made up of program communication blocks (PCBs). You define the 
PSB by defining its PCBs. The types of PCBs are: 

• DB (database) 

• TP (teleprocessing) 

• GSAM 

Each DB PCB describes one database hierarchy. In the IMS environment, PCBs 
also serve to identify IMS message queues or GSAM databases. 

You can pass individual PCBs on a call. This allows you to define a program 
with a PSB and call the program from other programs that have different PSB 
structures. You use the special function word EZEDLPCB, subscripted with 
the PCB number to be passed, on the CALL statement. 

Defining a program specification block (PSB) 

In the PSB Editor, you can define a set of DL/I database structures that a 
program can access. You can use program specification block (PSB) definitions 
to build and validate DL/I calls for I/O functions that access segments in 
DL/I databases. 

From the PSB Editor, you can create and edit PSBs. 
Editing PSBs 

1 . To open an existing PSB for editing, do one of the following: 

• From the File menu in the PSB Editor, select Open. 

• From the VAGen Parts menu, select 
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2. In the PSB Editor, select a PCB or segment in the list. Then select Insert 
Before or Insert After. 

If the PSB contains no PCB entries, select Insert Before or Insert After to 
add a new PCB. 

3. On the Choose Type window, specify the type of PCB, and select OK. 

Note: The PCB Restrictions table describes the restrictions on inserting 
PCBs into a PSB. 

4. Depending on the PCB type you select, you might be prompted to further 
define or update information for the PCB. Enter the appropriate 
information on the prompt window and select OK. 

5. To validate and correct any errors in the structure of the PSB, on the PSB 
Editor, from the Tools menu, select Validate Structure. 

PCB restrictions: 



Table 15. Restrictions for inserting PCBs into a PSB list 



PCB Type 


Restrictions for PCB types in a PSB 


TP 


Must come before all DB and all GSAM 


DB 


Must come after all TP and before all GSAM 


Segment 


Must come after a DB or between Segments 


GSAM 


Must come after all DB 



Data items 

Data items are used in records and tables. Data items can have one of the 
following usages within records and tables: 

Nonshared data items 

Nonshared data item definitions are stored with the record or table 
with which they are defined. Changes to a nonshared data item have 
no effect on definitions of data items with the same name in other 
records or tables. 

Shared data items 

Shared data items are saved as a separate part. They can be referenced 
by any other part. 

When you are creating a data item that is independent of a record or 
table, it is a shared data item. Changes to shared data items affect all 
the records and tables that include that data item as a shared data 
item. 

Within a Map Editor, the edit characteristics of a shared data item are 
used when: 
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• You drag a shared data item from a list of parts into the map 
definition. 

• You name a variable field the same name as a shared data item. 

Note: You can have shared data items created from the variable fields 
you create during map definition when you select Create data 
items from map fields on the VisualAge Preferences window, 
on the VAGen - Map tab. 

The following characteristics are dependent on the structure in which the data 
item is defined: Key item, level, occurs, read-only, scope, SQL column name, 
and SQL data code. 

The following characteristics are independent of the structure: Bytes, decimal 
positions, description, length, name, and type. 



Maps 

A map is a text-based user interface used to display information and receive 
input from users. Some general characteristics of maps are as follows: 

• All information on a map is represented by constant and variable fields. 

• Variable fields appear as outlined boxes. 

• Constant fields appear enclosed in brackets. 

• Brackets for the last constant field on the map wraps around to the top of 
the map if there is no field mark at the beginning position of the map. 

• There is no visual distinction between single byte, DBCS, and mixed fields. 
However, if you click on a field, the status area at the bottom of the map 
provides information about the selected field. 

• The rectangle on the map presentation area indicates the position of the 
map. The rectangle is positioned based on settings in the Layout tab on the 
Map Properties window. 

• When a map is blank, it is treated as if there is an implicit constant field to 
hold the text on the map. 

If you use an existing data item name when you name a variable field, any 
edit characteristics for the data item are automatically assigned to the map 
field. Changing the edit characteristics for the variable field does not affect the 
edit characteristics of the data item. 

If the name of the variable field is not the name of an existing data item, and 
you select Create data items from map fields (on the Map page of the 
Options /Preferences notebook), a new data item is automatically created 
when you save the map. 
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Each map is part of a named collection called a Map Group. Each map within 
a map group must have a unique name. All maps used in a program must be 
in the same map group, except for help maps, which can be in a separate map 
group. 

Defining map properties 

Use map properties to define characteristics applied to the entire map. To 
define map properties: 

1 . In the Map Editor, from the Define menu, select Map Properties. 

2. (Optional) To assign a help map, on the General tab, select the name of 
the help map and specify the key you want to display it. 

3. To define the size and position of the map, select the Layout tab and enter 
the appropriate values. If you want to create a floating map, select the 
Floating map check box. 

4. To define the devices that this map can be presented on, select the Devices 
tab. Select device types from the drop-down list box and use the arrow 
buttons to move devices from Available devices list box to the Supported 
devices list box. 

Defining constant fields 

A map is divided into fields. When you create a new field, beginning and 
ending field marks are automatically entered for you based on the field length 
you specify in properties. To add a constant field to the map: 

1. Select 




(Constant part) from the palette and place it on the map presentation area. 

2. On the Constant Field Properties window, specify the field attributes and 
select OK. 

Note: After you have created a constant field, you can edit its properties by 
double-clicking on the field to open the Constant Field Properties 
window. 

Defining variable fields 

A map is divided into fields. When you create a new field, beginning and 
ending field marks are automatically entered for you based on the field length 
you specify in properties. To add a variable field to the map: 
1 . Select 



(Variable part) from the palette and place it on the map presentation area. 
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2. On the Variable Field Properties window, specify the general field 
properties, attributes, edits, and error messages as needed. 

Note: On the Edits tab, you can specify General edits as soon as you have 
named the field on the General tab. The Numeric section of the 
Edits tab is only enabled when you select the Numeric edits check 
box on the General tab. 

3. Select OK. 

Note: After you have created a variable field, you can edit its properties by 
double-clicking on the field to open the Variable Field Properties 
window. 

Map arrays 

A map array is specified by giving the same name to each field in the array 
and by specifying a unique index (or subscript) for each field in the array. The 
array variables can be positioned anywhere on the map and the indices do 
not have to be in the same order as the fields appear on the map. All index 
values between 1 and the number of fields in the array must be used for the 
array to be valid; thus, no gaps in the index values are allowed. Use the 
Resequence Array Indices choice on the context menu to renumber array 
indices. 

All variable fields in a map array must have the same data type, length, and 
share the same map edit specifications. Hardware attributes might be different 
for each variable field in the map array. The hardware attributes can be set 
using the Attributes tab on the Variable Field Properties window or changed 
at run time using the SET statement. 

Defining map arrays 

Map arrays are groups of variable fields on a map. They are typically used to 
manage the same type of data and therefore have the same field length. 
Variable fields in an array also have the same name. Only the subscript or 
index number makes each field name unique. 

After you create a new map array, you can make changes to it by doing the 
following: 

• Editing map arrays 

• Extending map arrays 

• Checking map array indices 

Creating a new map array 

To place an array of variable fields on a map: 
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1. Select 



(Array part) from the palette and place it on the map. 

2. On the Variable Field Properties window, do the following: 

a. On the Array tab, specify the number of variable fields in the array 
and how you want to place them. 

b. In the Naming direction box, select the direction to be used first in 
numbering the variable fields. 

c. Select the General tab and type a name in the Name field to name the 
array. 

d. In the Length field, specify the length that will apply to every variable 
field in the array. 

e. In the Array index field, specify the value you want to start counting 
from. If you want to start numbering with the first element of the array 
variable, specify 1. 

For example, if the map array has 8 variable fields, your array variable 
is named QED, and you want to number the variable fields starting 
with the ninth element of QED, specify 9 in the Array index field. 

f. (Optional) Use the Attributes, Edits, and Error Message tabs to define 
other characteristics of your array. You can specify these characteristics 
now or you can edit them later. 

3. Select OK to place the map array in the map. 
Editing map arrays 

All variable fields in an array have the same name and properties specified 
when the array was created. To change the properties of all variable fields in 
an array: 

1 . Double-click on a variable field in an array. 

2. On the Variable Field Properties window, navigate through the tabs and 
make any necessary changes. 

3. Select Apply to Array, to apply your changes to all the variable fields in 
the array. Selecting OK applies your changes only to the variable field you 
have selected. 

Extending map arrays 

To extend an existing array: 

1 . Place the cursor where you want to put the first variable field in the 

extension by holding down the Alt key and clicking with mouse button 1 
outside the bounds of the existing array. 
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2. From the Map Editor Define menu, select New, then Array. 

3. On the Array tab, do one of the following: 

• Add one or more columns of variable fields to the existing array by 
specifying a number in the Fields across field. 

The values in the Fields down, Lines between, and Spaces between 
fields should match those values for the existing array. 

• Add one or more rows of variable fields to the existing array by 
specifying a number in the Fields down field. 

The values in the Fields across, Lines between, and Spaces between 
fields should match those values for the existing array. 

4. On the General tab, do the following: 

a. In the Name field, specify the name of the existing array that you are 
extending. 

Note: If you specify a different name, you will create a new array 
instead of extending the existing one. You can always rename 
the entire array after you have added an extension. 

b. Specify a length value for the variable fields you are adding. This 
value should match the lengths of the variable fields in the existing 
array. 

c. In the Array index field, specify the next sequential value from the 
existing array index. 

For example, if you want to extend an existing array that has four 
variable fields and you started indexing with the number one, you 
would enter the number five in the Array index field. 

5. Use the Attributes, Edits, and Error Message tabs to specify the same 
characteristics for the array extension as were specified for the existing 
array. 

6. Select OK. 

To ensure that the array is extended as you intended, check the array indices. 
If the field edit order number (the first number in the tag) is the same for all 
the variable fields in the array, you have successfully extended the array. 

Checking map array indices 

When you save a map, any invalid arrays are automatically resequenced. To 
check an array to ensure that it is indexed as you intended: 

• From the Map Editor Define menu, select Field Edit Order, then Show 
Tags. 

The first number in the tag is the field edit order number and the second 
number is the array index. If you see gaps in the indices, resequence the 
array. 
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• To resequence the array, click with mouse button 1 on one of the fields and 
select Resequence Array Indices from the context menu. Resequencing the 
array renumbers the variable fields in the array and ensures that there are 
no gaps in the array indices. 

Note: Resequence Array Indices is not available when the selected variable 
field is not part of an array. 

Viewing a map 

You can view a map two different ways: as your users will see it or with 
markings that make it easy for you to edit. 

To view the map as it is displayed for your users: 

• From the Map Editor View menu, select Preview. Select Preview again to 
continue editing the map. 

While you are editing the map, you can view it in run-time color mode or 
black and white. To change your view for editing a map: 

• From the View menu, select Runtime color mode. Your view changes from 
the default black and white to run-time color mode. 

• Select Runtime color mode again to go back to defining the map in black 
and white. 

Editing maps 

The following are some methods you can use to edit maps: 

• Inserting and editing text 

• Cutting, copying, and pasting 

• Selecting fields 

• Sizing fields 

• Dragging fields 

• Deleting fields 

• Inserting constants, variables, and arrays 

• Centering fields 

• Using the Field List 

Note: To type text in the Map Editor, you must be in edit mode. To enter edit 
mode, hold down the Alt key and click with mouse button 1 anywhere 
in the map presentation area. 

Inserting and editing text 

To go into edit mode, hold down the Alt key and click with mouse button 1 
anywhere within the map presentation area or within a field, then start 
typing. 

Once you are in edit mode, you can type text in the existing fields of a map 
or directly on a blank map. You can use the arrow keys and all other key 
strokes and selection behavior you can use in a standard text field. Editing 
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applies to the current field only and is limited to working within the current 
field on the current line. That is, no reflowing of text occurs when inserting 
and deleting characters. 

When you enter edit mode, all trailing blanks in the currently edited field or 
line are removed. This means that you will not be able to type in overtype 
mode when you reach the end of text on the field or line. In OS/2, press the 
Insert key to go into overtype mode. Overtype mode is not available in 
Windows. 

Using the arrow keys to move from a field or line automatically takes you out 
of edit mode for that field or line and commits the data you have entered. The 
destination field that the cursor moves to automatically opens in edit mode. If 
the cursor reaches the end of the text on the line, the right arrow key acts as a 
space bar and advances the cursor one position to the right. If the cursor 
reaches a field with a size of zero, the cursor will not be visible but the arrow 
keys will still function correctly. 

You cannot type over the field mark positions. Using the arrow key to move 
left or right into a field mark position automatically moves the cursor past the 
field mark position. 

Use the Tab key to move the cursor to the beginning of the next field or the 
back tab to move the cursor to the beginning of the previous field. 

Use the return key to move the cursor to the beginning of the next line. 

Use the Ctrl+End keys to move the cursor to the end of the map. Use the 
Ctrl+Home keys to move the cursor to the beginning of the map. 

In edit mode, use the Page Up and Page Down keys to scroll the map up or 
down. Use Ctrl+Page Up and Ctrl+Page Down to scroll the map left and 
right. 

Clicking anywhere within the bounds of a field that is currently being edited 
causes the cursor to move to that position in the field (You do not need to 
hold down the Alt key to do this.) 

To exit edit mode, click outside the bounds of the field being edited. This 
causes the text you entered to be committed. 

Selecting fields 

Select a field by placing the mouse pointer over the field you want to select 
and clicking mouse button 1. Two selection handles appear at the top left and 
bottom right positions of the field. 
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To select multiple fields: 

1 . Click mouse button 1 where you want to start your selection. 

2. Using the appropriate selection mode, drag to the point where you want 
to end the selection and release the mouse button. This step selects text in 
the highlighted area. 

3. From the Edit menu, select Selection, then Select Fields, to convert your 
text selection to a field selection. 

You can also select more than one field by holding down the Ctrl key and 
clicking on the fields you want to select. 

Deselect fields by holding down the Ctrl key and clicking on the fields you 
want to deselect. 

Sizing fields 

Select the field you want to size, click on the left or right selection handle (the 
cursor changes to a sizing pointer) while holding down mouse button 1 and 
drag the handles horizontally or vertically. 

Use the Grid to help you size fields appropriately. 

When you size a variable field to size 0, the variable field gets replaced by a 
constant field of size 0, since size 0 variable fields are not allowed. 

Press the Esc key to cancel a field sizing operation. 

Dragging fields 

Move any field on the map to a different position by clicking on it with 
mouse button 2 and dragging it to the new location. 

When you select a field to drag, the cursor changes to a cross hair and a 
dotted outline beside it. 

To move more than one field: 

1 . Select multiple fields by doing one of the following: 

• Drag the mouse pointer over the fields you want to select and 
selectEdit, then Selection, then Select Fields 

orPress and hold the Ctrl key and click the fields with mouse button 1. 

2. Click on one of the selected fields with mouse button 2 and drag the fields 
to the new location. If you click mouse button 2 on a field that is not part 
of your selection, your multiple-field selection will be ignored and you 
will drag only the field you clicked on with mouse button 2. 
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Deleting fields 

To delete fields, do the following: 

• Select the field or fields you want to delete and press the Delete key. 

• Select the field or fields you want to delete and from the Edit pull-down 
menu, select Delete, or select Delete from the context menu. 

Cutting, copying, and pasting 

To cut or copy text: 

1 . Select the text using the appropriate selection mode and drag the mouse 
pointer across the text until it is highlighted. 

2. From the Edit menu, select Cut or Copy. 

To paste text you have cut or copied: 

1 . From the Edit menu, select Paste. 

2. Place the mouse pointer (crosshair) where you want to paste the text and 
click once in the map presentation area. 

To cut or copy fields: 

1 . Using the appropriate selection mode, select the text you want to cut or 
copy. 

2. From the Edit menu, select Selection, then Select Fields, to convert your 
text selection to a field selection. 

3. From the Edit menu, select Cut or Copy. 

To paste fields you have cut or copied: 

1 . From the Edit menu, select Paste. 

2. Place the mouse pointer (crosshair) where you want to paste the fields and 
click once in the map presentation area. 

Note: If you duplicate any variable field names, you are prompted to 

rename the fields or have new names generated for them when you 
save the map. 

Inserting constants, variables, and arrays 

At the position where you want to insert text, hold down the Alt key and 
click mouse button 1. If there is text following the cursor position where you 
have clicked the mouse button, you might have to select that text and delete it 
first before you start typing. 

From the Define pull-down, select New to insert an array, variable, or 
constant field at the cursor position. The fields on the map are adjusted as 
necessary to preserve the data stream of the map. 
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Centering fields 

Select the field or fields you want to center, then from the Tools pull-down 
menu, select Center, or select the Center tool icon from the Tool bar. 

Variable Field Edits 

At rim time, when input data that is not valid is detected, the map is shown 
to the user along with an error message describing why the data is not valid. 
The user can enter correct data, or press a bypass PF key or any PA key to 
bypass input editing. 

Variable field edit elements are associated with the field name. All the fields 
in a map array share the same edit specifications. 

On the Variable Field Properties window, select the Edits tab to set variable 
field edit specifications. 

Listing maps by device 

To list maps in a defined map group that use a particular device: 

1 . Open the Map Group from which you want a list of maps. 

2. In the Map Group Editor, select the device you want to display a list for. 

3. From the Options menu, select List of Maps. 

4. Select Close. 

Note: You can only view a list of maps in map groups that have been fully 
defined. 

Creating a Ul record from a map 

For information about how to create a UI record from a map, see the 
"Record" section in this chapter. 
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Chapter 10. Developing MQSeries application systems 



Message queueing provides an alternative to remote procedure call 
communication between programs. With message queueing, programs 
communicate by writing to and reading messages from queues. 

Message Queue Interface (MQI) is an IBM specification of an application 
programming interface (API) for accessing message and queuing services that 
support data transfer between programs running on a wide variety of IBM 
and non-IBM platforms. The services allow programs to communicate without 
knowledge of the lower levels of the communication network and without 
knowledge of the location of the other programs. 

A message queue can be on the same system as a program (local) or on 
another system (remote). Queue managers manage access to queues and 
transmission of data between queues. 

An MQI message is a string of data sent from one program to another. An 
MQI message consists of program information and routing information used 
by the message queue manager (control information). The structure and content 
of the program information is determined by the communicating programs 
not by the queue manager. 

Programs that use message queueing techniques have the following features: 

• There is no physical connection between programs. 

• Communication network access functions are built into the queue 
managers, not into the programs. 

• Communicating programs can rim in parallel. 

• Communicating programs do not need to be running concurrently. 

• Intermittent communication link failures do not prevent messages from 
being delivered. 

• Work is carried out by small, self-contained programs. 

• Communication can be driven by events. 

• Messages can be assigned priorities. 

• Messages can be recoverable resources, committed or rolled back along with 
database or file updates. 

• Workloads can be balanced by starting multiple servers for processing a 
single queue. 

• Availability can be increased by assigning multiple alternative processors to 
service a queue. 



© Copyright IBM Corp. 2000 



227 



IBM MQSeries products implement the message queue manager on a variety 
of run- time platforms: 

• MQSeries for OS/390 Version 2 Release 1 

• MQSeries for VSE/ESA Version 2 Release 1 

• MQSeries for OS/2 Warp Version 5 Release 1 

• MQSeries for Windows NT Version 5 Release 1 

• MQSeries for AIX Version 5 Release 1 

• MQSeries for AS/400 Version 4 Release 2.1 

• MQSeries for HP-UX Version 5 Release 1 

• MQSeries for Sun Solaris Version 5 Release 1 

For more information on message queueing and the design of message 
queueing programs, refer to the following documents: 

• An Introduction to Messaging and Queueing (GC33-0805-01) 

• MQSeries MQI Technical Reference (SC33-0850) 

• MQSeries Application Programming Guide (SC33-0807-10) 

• MQSeries Application Programming Reference (SC33-1673-06) 

MQ programs are programs that access MQSeries message queues. In 
previous releases, VisualAge Generator supported development of MQ 
programs that access message queues through direct calls to VisualAge 
Generator APIs. In the current release, VisualAge Generator supports access to 
message queues through the serial file I/O options, ADD and SCAN. MQ API 
calls are still supported for compatibility with the previous releases. New 
development should be done using the file level interface. The file interface is 
supported in all runtime environments (with the exception of CICS for OS/2 
and SCO OpenServer) and in all types of programs, including web 
transactions, GUIs, and 3270 and batch programs. 

Subsequent sections of this chapter discuss how to implement MQ programs 
using either the file level interface or direct MQ API calls. 



Implementing MQ programs using the file level interface 

Developing MQ programs that use the file level interface includes: 

• Using sample programs 

• Defining messages in VisualAge Generator 

• Specifying the message queue name 

• Specifying MQSeries options for messages and queues 

• Specifying default values for programs that access message queues 

• Connecting to queue managers 
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• Writing messages to queues 

• Reading messages from queues 

• Committing or rolling back messages 

• Handling errors 

• Using linkage tables for MQSeries run time library selection 

• Testing MQ programs 

• Triggering programs when messages are placed on queues 

Using sample programs 

You can use sample programs shipped with VisualAge Generator to 
understand how to implement MQ programs using the file level interface. 
Refer to VisualAge Generator Getting Started for information on accessing 
sample programs and documentation. 

Defining messages in VisualAge Generator 

In VisualAge Generator, you can use a message queue record to store 
MQSeries message structure definitions. The record data item structure is the 
message format. Message queue records are similar to working storage 
records. In a message queue record, you can define message attributes. For 
example, you can define whether a message is included in a transaction with 
other messages. You can also specify other MQSeries options for messages 
and queues. 

The fundamental components of messages defined in VisualAge Generator for 
MQSeries message queues are the message buffer, the application data, and 
message attributes. The message buffer is defined as a data item definition in 
a message queue record. Application data for message queue records is 
handled like application data for other record types. Message attributes are set 
or defined in the Message Queue Record Properties window of the Record 
Editor. 

Defining message attributes 

You can set or define the following message attributes in the Message Queue 
Record Properties window of the Record Editor: 

• File name 

• Alternate specification 

• Include message in transaction 

• Open queue for exclusive use on input 

• Record length item 

• Occurrences item 

You can also define MQSeries options for messages and queues. See the 
section on MQSeries options for more information. 
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In the File name field, type a one-to-eight character name. The file name is 
used to associate the record with the system resource name in the resource 
association file used during test or generation. The system resource name for 
message queue records defines the queue manager name and queue name. 
The file name is also the default system resource name if one is not specified. 
The system resource name is used as the initial value for the EZEDEST item 
for the message queue record and identifies the default queue associated with 
the record. By default, the File name field is blank and a file name is not 
specified. 

Note: File name is a required property. You cannot save a message queue 
record if a file name is not specified. 

If the record item structure for the record you are defining needs to be exactly 
the same as the record item structure already defined for another record, type 
the name of the other record in the Alternate specification field. Use the 
Alternate specification field to avoid creating and maintaining equivalent 
record structures. When you change the original record structure, you change 
the structure of all records that refer to it as an alternate specification. There is 
no record structure defined for this record. VisualAge Generator uses the 
structure defined in the record named as the alternate specification. By 
default, the Alternate specification field is blank and an alternate 
specification is not defined. 

Select Include message in transaction to include the message as a recoverable 
resource in the program's unit of work. If an input message is a recoverable 
resource, it is not removed from the input queue until the unit of work is 
commited. If the unit of work is rolled back, the input message remains on 
the input queue for processing by a later transaction. If an output message is 
a recoverable resource, it is not written to the output queue until the unit of 
work is commited. If the unit of work is rolled back, the output message is 
deleted. If the message is not part of the transaction, it is not affected by 
commit or rollback of the unit of work. Input messages are deleted from the 
input queue when read, and placed on the output queue when written. By 
default, the Include message in transaction field is selected and the message 
is sent to the queue when you issue a commit request. 

VisualAge Generator automatically opens the message queue associated with 
the message record whenever a VisualAge Generator program reads messages 
from the queue through the SCAN I/O option. Select Open queue for 
exclusive use on input if you want VisualAge Generator to open the queue 
for input for only one program at a time. Deselect Open queue for exclusive 
use on input if you want VisualAge Generator to open the queue for input 
for more than one program at a time. By default, the Open queue for 
exclusive use on input field is deselected and exclusive queue access is not 
specified. 
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In the Record length item field, type the name of the data item that defines 
message length. 

When a program adds the record to a message queue, the message length is 
set equal to the value in the record length item. When a program reads the 
message from the queue, the message length is returned in the record length 
item. 

If the record contains both a record length item and occurrences item, the 
record length item is set to the length calculated from the number of 
occurrences before a message is added to the queue. 

By default, the Record length item field is blank and a record length item is 
not defined. 

If the record you are defining ends with an array item that can have a 
variable number of occurrences, type the name of the data item whose value 
represents the actual number of occurrences at run time in the Occurrences 
item field. The value can range from 0 to the maximum number of 
occurrences for the array which is the occurs value specified for the array 
item. 

The occurrences item must meet all of the following requirements: 

• Be defined in the record before the array item 

• Have a numeric data type 

• Have a maximum length of 9 digits with 0 decimal places 

You do not need to specify the name of the array item. It is assumed to be the 
last multiply occurring item in the record. The array item can be 
substructured. The array item cannot be followed by another item at the same 
level in the record. 

When VisualAge Generator adds the message queue record to a message 
queue, the message length is calculated as the length of the record structure 
without the array plus the occurrences item value multiplied by the length of 
an array item. 

By default, the Occurrences item field is blank and an occurrences item is not 
defined. 

Specifying the message queue name 

Specify the queue name as the system resource name for the message queue 
record in the resource association file, or code the program to move the queue 
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name to the EZEDEST special function word for the message queue record. 
See the section on specifying default values for information on defining the 
resource association file. 

Queue name format is queue_manager_name:queue_name. The 
queue_manager_name: is optional. If omitted, the default queue manager is 
used. 

If not specified, the default queue name is the file name defined in the 
message queue record properties. 

Specifying MQSeries options for messages and queues 

You can specify MQSeries options for messages and queues that describe a 
message, the queue and how each is used. In VisualAge Generator, MQSeries 
options are defined through record definitions. Record definitions are 
specified in the properties window of a message queue record. You can 
specify the following definitions: 

• Queue descriptor record 

• Open options record 

• Message descriptor record 

• Get options record 

• Put options record 

You can also use an alternate specification of a working storage record in 
combination with MQSeries options for messages and queues. 

Queue descriptor record 

VisualAge Generator programs call the MQSeries MQOPEN and MQCLOSE 
functions to open and close queues associated with message queue records. 
The MQOD, MQ Object Descriptor, structure is a parameter on MQOPEN and 
MQCLOSE calls. 

If you do not specify a Queue descriptor record, VisualAge Generator 
automatically builds a default MQOD structure. VisualAge Generator sets all 
fields to initial values, except for the object type, queue manager name and 
queue name. VisualAge Generator sets the object type to MQOT_Q for the 
queue. VisualAge Generator sets the queue manager name and queue name to 
the current values specified in EZEDEST for the record. If the queue manager 
name is not specified in EZEDEST, then a value for OBJECTQMGRNAME is 
not specified. OBJECTQMGRNAME and OBJECTNAME values are critical 
when you want to change queue managers before putting or getting 
messages. 
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If you need to specify other MQOD options or access information returned in 
the MQOD structure, you can use the MQOD working storage record shipped 
with the sample MQ programs. 
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Figure 20. MQOD record definition 



You can specify MQOD or the name of an alternate specification of MQOD to 
automatically include the record you specify in your program. Code the 
program to initialize and set fields in the MQOD record before accessing the 
queue. VisualAge Generator uses your MQOD structure instead of the default 
structure. 



Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQOD structure. 

Open options record 

VisualAge Generator programs call the MQSeries MQOPEN and MQCLOSE 
functions to open and close queues associated with message queue records. A 
four-byte binary options field is one of the parameters on the MQOPEN and 
MQCLOSE calls. 

If you do not specify an Open options record, VisualAge Generator 
automatically builds a default options parameter. On an open for an ADD, the 
options parameter is set to MQOO_OUTPUT + MQOO_FAIL_IF_QUIESCING. 
On open for exclusive use for a SCAN, the options parameter is set to 
MQOO_INPUT_EXCLUSIVE + MQOO_FAIL_IF_QUIESCING. On open for 
shared use for a SCAN, the options parameter is set to 
MQOO_INPUT_SHARED + MQOO_FAIL_IF_QUIESCING. On close, the 
options parameter is set to MQCO_NONE. 



Chapter 10. Developing MQSeries application systems 233 



If you need to specify other option values, you can use the MQOO working 
storage record shipped with the sample MQ programs. 
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Figure 21. MQOO record definition 



You can specify MQOO or the name of an alternate specification of MQOO to 
automatically include the record you specify in your program. Set options you 
need in the MQOO option item before opening and closing the queue. 
VisualAge Generator uses your MQOO options as the options parameter 
instead of the default options. 

Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQOPEN and MQCLOSE options. 

Message descriptor record 

VisualAge Generator programs call the MQSeries MQGET and MQPUT 
functions to implement the ADD and SCAN options for message queue 
records. The MQMD, MQ Message Descriptor, structure is a parameter on 
MQGET and MQPUT calls. 

If you do not specify a Message descriptor record, VisualAge Generator 
automatically builds a default MQMD structure. VisualAge Generator sets all 
the MQMD fields to their initial default values. 

If you need to set any MQMD fields to values other than the default values or 
access information returned in the MQMD structure, you can use the MQMD 
working storage record shipped with the sample MQ programs. 
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Figure 22. MQMD record definition 



You can specify MQMD or the name of an alternate specification of MQMD to 
automatically include the record you specify in your program. Code the 
program to initialize and set fields in the MQMD record before accessing the 
queue. VisualAge Generator uses your MQMD structure instead of the default 
structure. 



Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQMD structure. 

Get options record 

VisualAge Generator programs call the MQSeries MQGET function to 
implement the SCAN option for a message queue record. The MQGMO, MQ 
Get Message Options, structure is a parameter on the MQGET call. 

If you do not specify a Get options record, VisualAge Generator automatically 
builds a default MQGMO structure, setting the MQGMO_SYNCPOINT or 
MQGMO_NO_SYNCPOINT options based on whether you defined the 
message queue record to include the message in your transaction. 
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If you need to specify other get options or access information returned in the 
MQGMO structure, you can use the MQGMO working storage record shipped 
with the sample MQ programs. 
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Figure 23. MQGMO record definition 



You can specify MQGMO or the name of an alternate specification of 
MQGMO to automatically include the record you specify in your program. 
Code the program to initialize and set options in the MQGMO record before 
scanning the queue. VisualAge Generator uses your MQGMO structure 
instead of the default structure. 



Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQGMO structure. 

Put options record 

VisualAge Generator programs call the MQSeries MQPUT function to 
implement the ADD option for a message queue record. The MQPMO, MQ 
Put Message Options, structure is a parameter on the MQPUT call. 

If you do not specify a Put options record, VisualAge Generator automatically 
builds a default MQPMO structure. VisualAge Generator sets the 
MQPMO_SYNCPOINT or MQPMO_NO_SYNC POINT options based on 
whether you defined the message queue record to include the message in 
your transaction. 

If you need to specify other put options or access information returned in the 
MQPMO structure, you can use the MQPMO working storage record shipped 
with the sample MQ programs. 
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Figure 24. MQPMO record definition 



You can specify MQPMO or the name of an alternate specification of MQPMO 
to automatically include the record you specify in your program. Code the 
program to initialize and set options in the MQPMO record before adding any 
messages to the queue. VisualAge Generator uses your MQPMO structure 
instead of the default structure. 



Please refer to the MQSeries Application Programming Reference (SC33-1673-06) 
for further information on MQPMO structure. 

Alternate record specification and MQSeries options 

If you need more than one copy of an options record for use with different 
message queue records in the same program, you can define new records as 
alternate specifications of the options records. Alternate specification is a 
property of the new record definition that specifies that the record has the 
same data item definition as the record named in the property. 

Specifying default values for programs that access message queues 

You can define resource associations to specify default values for VisualAge 
Generator programs that access message queues. 

Use resource associations for: 

• Defining the queue manager name and queue name 

• Defining the system 

• Converting message formats 



Chapter 10. Developing MQSeries application systems 237 



To define a resource associations part for message queues: 

1 . Create a resource association part. 

2. Specify the file name 

Specify the file name as shown in the following example: 
FILE=filename 

The entry will be used for any message queue record with the same file 
name. 

3. Specify the file type 

Set the file type as shown in the following example: 

/FILETYPE=MQ 

4. Specify the system resource name 

You should specify the system resource name as shown in the following 
example: 

/SYSNAME=queue_manager_name:queue_name 

or, specify only the queue_name if you want to use the default queue 
manager. 

The system resource name for message queue records defines the queue 
manager name and queue name. The system resource name is used as the 
initial value for the EZEDEST item for the message queue record and 
identifies the default queue associated with the record. 

VAGen uses the system resource name on ADD and SCAN I/O operations 
for the message queue record. The queue name identifies the queue that is 
accessed by the operation. The queue manager name identifies the queue 
manager on which the queue is defined. The default queue manager is the 
queue manager to which the program is connected. 

If there is not already an active connection, VAGen uses the queue 
manager name to connect to the queue manager before accessing the 
queue. If no queue manager name is specified, VAGen connects to the 
default queue manager for the system. 

If the system resource name is not specified in a resource association file, a 
default system resource name is defined by the File name property of the 
message queue record. 

5. Specify the system name 

Specify the system name as shown in the following example: 
/SYSTEM=system_name 

6. Specify a conversion table name if you want data format conversion to be 
performed on the message 
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If you want data format conversion to be performed on the message, 
specify a conversion table name as shown in the following example: 
/CONTABLE=conversi on_table_name 

Because of the differences in character and numeric data formats between 
environments, your program might have to convert data as it is passed 
between a local format, such as the client machine, and a remote format, 
such as the server machine running the message queue. In VAGen 
programs, you can convert data based on the data item definition of the 
parameters or record structures as defined to the program. 

The type of conversion required is defined using a VAGen conversion 
table. Implementation of conversion tables varies with the environment. 
Refer to the VisualAge Generator Client/Server Communications Guide for 
more information on conversion tables. 

If a conversion table is specified, VAGen converts the message from local 
format to remote format when the message is added to the queue, and 
from remote format to local format when the message is read from the 
queue. VAGen performs conversion using the message queue record 
structure to identify the data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the EZECONVT 
special function word. 

Connecting to queue managers 

You can connect to only one queue manager at a time in a VisualAge 
Generator program. 

VisualAge Generator automatically connects to the queue manager on the first 
ADD or SCAN in a program, using the queue manager name specified in the 
system resource name associated with the message queue record. If the queue 
manager name is not specified, the queue manager is the default queue 
manager defined for your system. VisualAge Generator automatically 
disconnects from the queue manager when the program ends, closing any 
open files and commiting the current unit of work if it is still open. 

If the connection queue manager and the queue manager to which the queue 
belongs are different, use the MQCONN reusable part to connect before 
issuing the ADD or SCAN in the program. The ADD or the SCAN will use 
the current open connection instead of attempting to connect to the queue 
manager specified in the system resource name. 
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If you want a long running program to disconnect from the queue manager 
before the program ends, use the MQCONN reusable part to do the initial 
connection and the MQDISC part to disconnect after all queue access is 
complete. 

The MQCONN and MQDISC parts are described in the section on using 
direct MQ API calls. In workstation environments (Windows NT, OS/2, AIX, 
Solaris, and HP), MQSeries provides different runtime libraries for MQ 
programs depending on whether the program is running on the same system 
as the message queue manager or whether the program is running as an MQ 
client communicating with a manager on a server system. On AIX and HP 
systems, different libraries are provided for threaded and non-threaded 
environments as well. 

Writing messages to queues 

The process for writing messages to queues depends on whether you want to 
write messages to queues on the same queue manager or write messages to 
queues on different queue managers. In both cases, you can write messages to 
queues using the ADD I/O option with the message queue record as the I/O 
object. 

You can write messages to queues on the same queue manager using the 
ADD I/O option. When you use the ADD I/O option, Visual Age Generator: 

1 . Establishes the connection to the queue 

2. Opens the connection to the queue 

3. Puts the message on the queue 

You can write messages to a queue on another Queue Manager using the 
ADD I/O option. If you previously wrote a message to a queue using the 
ADD I/O option, you must use a local definition of the remote queue on the 
currently connected queue manager. 

Visual Age Generator saves the connection handle for future ADD calls. 

You must use the CLOSE I/O option after an ADD call to close the connection 
to the queue: 

• Before using the SCAN I/O option 

• To release the queue for access by another program 

• To release the queue if you have a long running program and have 
completed work with the queue 

VisualAge Generator automatically closes the connection to the queue on 
program termination. 
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Reading messages from queues 

The process for reading messages from queues depends on whether you want 
to read messages from queues on the same queue manager or read messages 
from queues on different queue managers. In both cases you can use the 
SCAN I/O option with the message queue record as the I/O object to read a 
message. 

You can read messages from queues on the same queue manager using the 
SCAN I/O option. When you use the SCAN I/O option, Visual Age 
Generator: 

1 . Connects to the queue manager, if the queue manager is not already 
connected 

2. Opens the queue, if the queue is not already open 

3. Gets the next message from the queue 

You can read messages from queues on different queue managers using the 
SCAN I/O option. If you previously read a message from a queue using the 
SCAN I/O option, you must use a local definition of the remote queue on the 
currently connected queue manager. 

You must use the CLOSE I/O option after a SCAN call to close the connection 
to the queue: 

• Before using the ADD I/O option 

• To release the queue for access by another program 

• To release the queue if you have a long running program and have 
completed work with the queue 

VisualAge Generator automatically closes the connection to the queue on 
program termination. 

Committing or rolling back messages 

When you combine messages in a transaction that defines a unit of work 
(UOW), the messages can be committed or rolled back as a group. When a 
UOW is committed, everything included in the transaction is finalized. When 
a UOW is rolled back, everything included in the transaction is removed. 

The methods used for commits and rollbacks depend on your environment. 
The following environments handle commits and rollbacks independently of 
MQSeries: 

• AS/400 

• CICS for MVS/ESA 

• CICS for VSE/ESA 

• IMS 
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In these transaction environments, message queue commits and rollbacks are 
coordinated with commits and rollbacks for other recoverable resources, like 
DB2 databases, using a two-phase commit protocol. 

In other environments, the resources for different managers are committed 
independently from one another. VisualAge Generator automatically issues 
the appropriate MQSeries calls for commits and rollbacks when you use 
EZECOMIT and EZEROLLB. 

Handling errors 

You can use VisualAge Generator support for automated error handling or 
custom error handling. You can select automated error handling by setting 
EZEFEC to 0 or custom error handling by setting EZEFEC to 1. 

Error handling involves the following types of errors: 
Hard errors 

Errors that cause the program to abnormally end 
Soft errors 

Errors that do not cause the program to abnormally end 
Handling hard errors 

There are considerations for automated and custom error handling of hard 
errors. 

If you enable automated error handling by setting EZEFEC to 0 and a hard 
error is encountered during an ADD or CLOSE operation, the error is handled 
differently based on your environment. On the workstation, VisualAge 
Generator sets the CMCOMP structure and terminates the program. On host 
systems, VisualAge Generator calls error services to handle the error. 

If you enable custom error handling by setting EZEFEC to 1 and a hard error 
is encountered during an ADD or CLOSE operation, VisualAge Generator 
sets: 

• EZERT2 with the completion code 

• EZERT8 with the reason code 

• The I/O error value for the message queue record 

After VisualAge Generator returns the completion code, reason code and I/O 
error value, program execution continues. 

Use conditional coding in your program based on the MQSeries reason codes 
to handle hard errors. For hard errors when EZEFEC is set to 1, MQSeries 
reason codes are written to EZERT8. 
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Handling soft errors 

If a soft error occurs on an ADD, SCAN or CLOSE due to MQSeries reason 
codes MQRC_TRUNCATED_MSG_ACCEPTED or 

MQRC_NO_MSG_ AVAILABLE, VisualAge Generator will not terminate the 
program. 

Use conditional coding in your program based on the MQSeries reason codes 
to handle soft errors. For soft errors, MQSeries reason codes are written to 
EZERT8. 

Using linkage tables for MQSeries run time library selection 

Use a VisualAge Generator linkage table part to indicate which runtime 
library you want to use. The MQ reusable parts shipped with VisualAge 
Generator include sample linkage tables for all supported environments. The 
following table shows which linkage table part to use in each environment. 
You can use the linkage table parts directly, or copy the entries in the parts to 
your own linkage table, if you need to specify entries for other program calls. 



Table 16. Linkage Tables for MQ Programs 



Environment 


MQSeries Library 
Description 


MQSeries Library 


Wrapper DLL 
Name 


Linkage Table 


Windows 


MQ manager 


mqm.lib 


csomqm32 


mqm32.1kg 


Windows 


MQ client 


mqic32.1ib 


csomqc32 


mqic32.1kg 


OS/2 


MQ manager 


mqm.lib 


csomqm 


mqm.lkg 


OS/2 


MQ client 


mqic.lib 


csomqic 


mqic.lkg 


AIX 


MQ manager 


libmqm.a 


csomqm 


libmqm.lkg 


AIX 


MQ client 


libmqic.a 


csomqic 


libmqic.lkg 


AIX 


MQ manager, 

threaded 

environment 


libmqm_r.a 


csomqmr 


libmqm_r.lkg 


AIX 


MQ client, threaded 
environment 


libmqic_r.a 


csomqicr 


libmqic_r.lkg 


HP-UX 


MQ manager 


libmqm.sl 


csomqm 


libmqm.lkg 


HP-UX 


MQ client 


libmqic.sl 


csomqic 


libmqic.lkg 


HP-UX 


MQ manager, 

threaded 

environment 


libmqm_r.sl 


csomqmr 


libmqm_r.lkg 


HP-UX 


MQ client, threaded 
environment 


libmqic_r.sl 


csomqicr 


libmqic_r.lkg 


Solaris 


MQ manager 


libmqm.so 


csomqm 


libmqm.lkg 


Solaris 


MQ client 


libmqic.so 


csomqic 


libmqic.lkg 
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If you are testing or running with an MQ manager, non-threaded library, 
specify the linkage table part as a test or generation option. If you are testing 
or running with an MQ client or threaded library, you must also move the 
part to a file and set the CSOLINKTBL environment variable to the file name. 

Generated Java programs require a special format for the linkage table entry. 
The entry should look like the following: 

: cal 1 1 i nk appl name=el aq* 1 ibrary=mq_wrapper_dl l_name 1 i nktype=csocal 1 

parmform=commptr remotecomtype=di rect remoteapptype=nonvg 
contabl e=java_conversi on_tabl e_name 

where the mq_wrapper_dll is the wrapper dll name for your runtime 
environment from the previous chart, and the java_conversion_table_name is 
the java conversion table correct for your language and the system on which 
the program is running. Refer to the VisualAge Generator Client /Server 
Communications Guide for help in determining which conversion table to 
choose. 

Testing MQ programs 

You can use the test facility to develop and test almost all MQ program logic. 
Define and debug the logic of both client and server programs using the 
VisualAge Generator test facility and local OS/2 queues. After the program 
logic is validated, you can generate for the appropriate run-time environments 
and perform the final production test with remote queues and local message 
queues. 

Before you can begin testing an MQ program, you need to define resource 
associations. 

To define resource associations in the VisualAge Generator test facility for 
message queues: 

1 . Select Tools-»Resource Associations File. In the Resource Association File 
Window, select the Add button. 

2. Specify the file name 

Type the file name in the Logical name field of the Primary Specification 
Window. The entry will be used for any message queue record with the 
same file name. 

3. Specify the file type 

Select Message Queue in the Organization field of the Primary 
Specification Window. 

4. Specify the system resource name 

Type the queue manager name and queue name in the Physical name 
field of the Primary Specification Window as shown in the following 
example: 
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queue_manager_name:queue_name 

The system resource name for message queue records defines the queue 
manager name and queue name. The system resource name is used as the 
initial value for the EZEDEST item for the message queue record and 
identifies the default queue associated with the record. 

VAGen uses the system resource name on ADD and SCAN I/O operations 
for the message queue record. The queue name identifies the queue that is 
accessed by the operation. The queue manager name identifies the queue 
manager on which the queue is defined. The default queue manager is the 
queue manager to which the program is connected. 

If there is not already an active connection, VAGen uses the queue 
manager name to connect to the queue manager before accessing the 
queue. If no queue manager name is specified, VAGen connects to the 
default queue manager for the system. 

If the system resource name is not specified in a resource association file, a 
default system resource name is defined by the File name property of the 
message queue record. 

5. Specify a conversion table name 

If you want data format conversion to be performed on the message, type 
a conversion table name in the Physical name field of the Primary 
Specification Window. 

Because of the differences in character and numeric data formats between 
environments, your program might have to convert data as it is passed 
between a local format, such as the client machine, and a remote format, 
such as the server machine running the message queue. In VAGen 
programs, you can convert data based on the data item definition of the 
parameters or record structures as defined to the program. 

The type of conversion required is defined using a VAGen conversion 
table. Implementation of conversion tables varies with the environment. 
Refer to the VisualAge Generator Client/Server Communications Guide for 
more information on conversion tables. 

If a conversion table is specified, VAGen converts the message from local 
format to remote format when the message is added to the queue, and 
from remote format to local format when the message is read from the 
queue. VAGen performs conversion using the message queue record 
structure to identify the data type of fields in the message. 

Specify EZECONVT for the conversion table name if you want the 
conversion table name to be picked up at run time from the EZECONVT 
special function word. 

6. Click the OK button and close the Resource Association File Window. 
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When testing with MQ, make sure to specify the linkage table appropriate for 
your environment in the VAGen Test Linkage Preferences. 

Triggering programs when messages are placed on queues 

Some MQSeries applications that serve queues run continuously so they are 
always available to retrieve messages that arrive on the queues. However, this 
may not be desirable when the number of messages arriving on the queues is 
unpredictable. In this case, applications could be consuming system resources 
even when there are no messages to retrieve. 

MQSeries provides a facility that enables an application to be started 
automatically when there are messages available to retrieve. This facility is 
known as triggering. 

Refer to the MQSeries Application Programming Guide (SC33-0807-10) for 
information on the following topics: 

• What is triggering? 

• Prerequisites for triggering 

• Conditions for a trigger event 

• Controlling trigger events 

• Designing an application that uses triggered queues 

• Trigger monitors 

• Properties of trigger messages 

• When triggering does not work 

Refer to MQSeries Intercommunication (SC33-1872-03) for information about 
triggering channels. 



Implementing MQ programs using direct MQ API calls 

Developing VisualAge Generator programs that use direct MQ API calls 
includes: 

• Using sample programs 

• Defining messages in VisualAge Generator 

• Specifying MQSeries options for messages and queues 

• Connecting to queue managers 

• Converting message formats 

• Writing messages to queues 

• Reading messages from queues 

• Committing or rolling back messages 

• Handling errors 

• Specifying linkage tables for MQ programs 

• Testing MQ programs 
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Using sample programs 

The MQI is a set of program interfaces used to request services from the 
message queue manager. The following functions are supported: 

• Connecting and disconnecting from the queue manager (MQCONN or 
MQCONNX, MQDISC) 

• Opening and closing a queue (MQOPEN, MQCLOSE) 

• Reading a message from a queue (MQGET) 

• Writing a message to a queue (MQPUT) 

• Writing a single message to a queue with an implicit open and close of the 
queue (MQPUT1) 

• Requesting or setting attributes of a queue manager object such as a queue 
(MQINQ, MQSET) 

• Beginning a unit of work (MQBEGIN) 

• Committing or backing out changes (MQCMIT, MQBACK) 

VisualAge Generator provides sample functions that call the appropriate entry 
point on the workstation or mainframe. The sample functions have the same 
name as the MQAPI that they call. For example, the function that calls the 
MQPUT API is name MQPUT. The functions assume the parameters are 
defined and initialized using the sample records. The groups and parameter 
definitions can be reused in any MQ program definition. 

Four sample programs show how to use MQI calls manually within 
VisualAge Generator batch, 3720, GUI and Web client programs. The 
programs use common record and function definitions for calling MQI entry 
points. The sample programs can be loaded from the following .dat files: 

• For VisualAge Generator Developer on Smalltalk, 
c:\Program FilesWAST\samples\MQS.DAT ( for NT) or 
c:\VAST\samples\MQS.DAT (for OS2): contain the Smalltalk application 
HptSampleMQApp. See VisualAge Generator Getting Started for detailed 
information on importing and loading applications. 

• For VisualAge Generator Developer on Java, 
IBMVJava\IDE\program\samples\MQJ.DAT contains the Java 
project\ package VAGen MQ SampleXibm.com.vgj.sample.mq. See 
VisualAge Generator Getting Started for detailed information on importing 
and loading projects and packages. 

MQ3270 - VisualAge Generator MQI sample program for 3270 
environments 

You can use MQ3270 to write and read messages from a queue. The messages 
are deleted when you read them. Messages are typed and displayed in an 
array on a 3270 map. 
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Enter the message queue manager name and the message queue name in the 
map before reading or writing messages. 

The following keys are supported: 
F3/F12 Quit 

F8 Read and display up to 10 messages from the queue. When a message 
is read, it is removed from the queue. 

F9 Write any messages currently in the message array on the screen to 
the queue. 

MQGUI and MQWEB - VisualAge Generator MQI sample programs for GUI 
and Web environments 

You can use MQGUI or MQWEB to write and read messages from a queue. 
The messages are deleted after you read them. 

You must enter the message queue manager name and the message queue 
name in the window before reading or writing messages. 

The following pushbuttons are supported: 
Quit Leave the program. 
Get Messages 

Read and display up to 20 messages in a table on the window. 
Put Messages 

Write the message text that is in the window's Message to put to 
queue field to the queue. Repeat the write operation for the repetition 
count entered on the window. 

MQBATCH - VisualAge Generator MQI sample batch program 

MQBATCH tests each MQI function and prints a simple report to the 
EZEPRINT file. This report indicates whether the functions completed 
successfully. MQBATCH uses the default queue manager and requires a queue 
named TESTQUEUE with a message length of at least 100 characters. 

Four tests are performed: 
Put/Get 

Writes a single message to TESTQUEUE and reads it back 
Commit 

Verifies that commit and rollback functions work with messages in 
supported environments 

Inquiry 

Exercises the inquiry function to retrieve queue attributes 
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Set Exercises the set function to prevent writes to TESTQUEUE and 
verifies that the function was effective 



Reusable parts from the sample programs 

Parameter definitions: MQI parameters are either data items or records. 
Refer to the MQSeries MQI Technical Reference for a complete description of the 
MQI parameters. 

MQSTATE and MQ ATTRIBUTES, sample records, contain declarations for 
most data item parameters. Parameter names are the same as in the parameter 
declarations shown in the MQSeries MQI Technical Reference 

The BUFFER parameter (message buffer parameter used with MQGET, 
MQPUT, and MQPUT1 calls) and the CHARATTRS (character attributes buffer 
parameter used with MQINQ and MQSET calls) are both defined with a 
length of 1024 characters. Increase the length of these items if you reuse 
MQSTATE in a program that requires larger buffers. 

Data structures: Sample records are provided to define the format of record 
parameters and special purpose messages and message headers. Record 
names are the same as the COBOL and C structure names. The data items in 
the records have the same names as the corresponding fields in the COBOL 
and C structures, except that the COBOL names use a hyphen (-) as a token 
separator instead of an underscore. 

The following is a list of structure records: 
MQBO 

Begin options 

MQCNO 

Connect options 

MQDH 

Distribution header 

MQDLH 

Dead-letter header 

MQGMO 

Get-message options parameter 

MQINTATTRS 

Integer attributes parameter 

MQMD 

Message descriptor parameter 
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MQMD1 

Message descriptor (version 1) 

MQMDE 

Message descriptor extension 

MQOD 

Object descriptor parameter 

MQOR 

Object record 

MQPMO 

Put-message options structure 

MQRMH 

Message reference header 

MQRR 

Response record 

MQSELECTORS 

Attribute selectors parameter 

MQTM 

Trigger message structure 

MQTMC2 

Trigger message 2 (character format) 

MQXQH 

Transmission queue header 

Functions for initializing structure parameters: The following sample 
functions can be used to initialize structure parameter fields to their default 
values: 

MQBO_INIT 

Initialize begin options 

MQCNOJNIT 

Initialize connect options 

MQDHJNIT 

Initialize distribution header 

MQDLH_INIT 

Initialize dead-letter header structure 

MQGMO_INIT 

Initialize get-message options structure 

MQMDJNIT 

Initialize message descriptor structure 
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MQMD1JNIT 

Initialize message descriptor (version 1) 

MQMDE_INIT 

Initialize message descriptor extension 

MQOD_INIT 

Initialize object descriptor structure 

MQOR_INIT 

Initialize object record 

MQPMO_INIT 

Initialize put-message options structure 

MQRMH_INIT 

Initialize message reference header 

MQRRJNIT 

Initialize response record 

MQSTATEJNIT 

Initialize item parameters and system state values 

MQTM_INIT 

Initialize trigger message structure 

MQTMC2_INIT 

Initialize trigger message 2 (character format) 

MQXQHJNIT 

Initialize transmission queue header structure 

Functions for calling MQSeries APIs: The following sample functions can 
be used to call MQSeries APIs: 

MQCONN 

Connect to message queue manager 

MQCONNX 

Extended connect 

MQDISC 

Disconnect from message queue manager 

MQOPEN 

Open a message queue 

MQCLOSE 

Close a message queue 

MQGET 

Read a message from a queue 
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MQPUT 

Write a message to a queue 

MQPUT1 

Write a single message to a queue including queue open and close 

MQINQ 

Inquire about queue attributes 

MQSET 

Set queue attributes 

MQBEGIN 

Begin a logical unit of work 

MQCMIT 

Commit a logical unit of work 

MQBACK 

Back out a logical unit of work 

Constants and return codes: The values for MQ parameters are set using 
constants. In the sample programs, constant values are defined in table 
MQVALUE and return codes in table MQRC. Another table, MQRCODE, is 
used in the sample programs as a look-up table that associates a return code 
with the return code description. 

The VisualAge Generator constants and return codes have the same names as 
the MQI constants defined for C or COBOL. Like the C constants, the 
VisualAge Generator version of the constant names uses an underscore^) 
instead of a hyphen(-) as a token separator in the constant name. 

One constant, MQENC -NATIVE (numeric encoding format for current 
environment), is defined as a data item in the MQSTATE working storage 
record. The MQSTATE JNIT function sets the value of MQENC-NATIVE 
based on the system on which the program is running. 

Defining messages in VisualAge Generator 

The two fundamental components of messages defined in an MQ program 
that uses direct MQ API calls are the message buffer and application data. The 
message buffer is defined as a data item definition in a working storage 
record. The application data is defined explicitly or implicitly through 
functions. 

Use working storage records to store MQSeries message structure definitions. 
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Defining message buffers 

You can define message buffers for manual MQI calls by creating data item 
definitions in working storage records. Data item definitions can be shared 
with other working storage records or used exclusively by a single record. 

Defining application data 

You can define application data explicitly or implicitly. 

You can define application data explicitly by assigning values to data items 
that represent message buffers. Assign a value in a function to a data item 
defined in a working storage record. For example, if you define a working 
storage record with a data item named col ors, you could define the 
application data explicitly with the following code in a function: 
colors="red, green and blue"; 

In this example the message buffer is defined as a data item named col ors 
and the application data is defined explicitly as red, green and blue. 

You can define application data implicitly by assigning values from data items 
to data items that represent message buffers. Assign a value in a function to a 
data item defined in a working storage record. For example, if you define a 
message queue record with a data item named col ors, and you have a data 
item named primary that contains the literal string red, green and blue; you 
could define the application data implicitly with the following code in a 
function: 

col ors=primary ; 

In the example, the message buffer is colors and the application data is 
defined as red, green and blue, a literal string passed into the message 
buffer from a data item named primary. 

Specifying MQSeries options for messages and queues 

You can specify MQSeries options for messages and queues that describe a 
message, the queue and how each is used. In VisualAge Generator, MQSeries 
options are manually defined through function definitions. 

Values for MQI options are set using constants from the MQVALUE table. 

To specify an option to MQI, code a statement to assign the constant to the 
appropriate options variable. 

For example, to indicate open for output, code: 
MQSTATE. OPTIONS = MQ00_0UTPUT ; 

To set multiple options, assign the sum of the constants to the options 
variable, as shown below: 
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MQGMO .GETOPTIONS = MQGMO_LOCK 

+ MQGMO_ACCEPT_TRUNCATED_MSG 
+ MQGMO_BROWSE_FIRST ; 

Connecting to queue managers 

You can connect to only one queue manager at a time in a VisualAge 
Generator program. 

You connect to a queue manager with an MQCONN call in a function. If you 
want to use the default queue manager, leave the queue manager name field 
blank when you define the MQCONN call. 

Converting message formats 

The format of the program message data is not known to the message queue 
manager. Format conversion for program message data is the responsibility of 
the program. VisualAge Generator programs can use the EZECONV function 
in environments where it is supported to perform format conversion. 

To determine if message format conversion is required, a program can check 
the CodedCharSetld field (character set) and Encoding field (numeric data 
formats) in the message descriptor to determine if conversion is required. 

To avoid numeric field conversions altogether for VisualAge Generator 
programs, use packed decimal for numeric fields in messages. 

Writing messages to queues 

The process for writing messages to queues depends on whether you want to 
write messages to queues on the same queue manager or write messages to 
queues on different queue managers. In both cases you can use MQSeries calls 
to manually write messages to queues. 

Note: You must close and disconnect from the queue manually after the final 
MQPUT of the transaction. 

You can write messages to queues on the same queue manager manually 
using MQSeries calls: 

1 . Connect to the queue using MQCONN 

When you write a message to a queue, you can: 

• Include the message in a transaction 

• Exclude the message from a transaction 

2. Open a connection to the queue using MQOPEN 

3. Write a message to the queue using MQPUT 

4. Close the queue using MQCLOSE 

5. Disconnect from the queue using MQDISC 
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Disconnect from the queue when you want to commit the transaction and 
separate the transaction from any future calls. 

You can write messages to queues on different queue managers manually 
using MQSeries calls. If you previously wrote messages to queues manually 
using MQSeries calls, you must disconnect from the currently connected 
queue manager before writing a message to a queue on another queue 
manager. 

Once you disconnect from the queue manager using MQDISC, you can write 
a message to a queue on a new queue manager using the MQSeries calls: 
MQCONN, MQOPEN, MQPUT, MQCLOSE and MQDISC. 

Reading messages from queues 

The process for reading messages from queues depends on whether you want 
to read messages from queues on the same queue manager or read messages 
from queues on different queue managers. In both cases you can use 
MQSeries calls to manually read messages from queues. 

Note: You must close and disconnect from the queue explicitly after the final 
MQGET of the transaction. 

You can read messages from queues on the same queue manager using 
MQSeries calls: 

1 . Connect to the queue using MQCONN 

When you write a message to a queue, you can: 

• Include the message in a transaction 

• Exclude the message from a transaction 

2. Open a connection to the queue using MQOPEN 

3. Write a message to the queue using MQGET 

4. Close the queue using MQCLOSE 

5. Disconnect from the queue using MQDISC 

Disconnect from the queue when you want to commit the transaction and 
separate the transaction from any future calls. 

You can read messages from queues on different queue managers manually 
using MQSeries calls. If you previously read a message from a queue 
manually using MQSeries calls, you must manually disconnect from the 
currently connected queue manager before reading a message from a queue 
on another queue manager. 

Once you disconnect from the queue manager using MQDISC, you can read a 
message from a queue on a new queue manager using the MQSeries calls: 
MQCONN, MQOPEN, MQGET, MQCLOSE and MQDISC. 
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Committing or rolling back messages 

Messages are treated as recoverable resources if the MQGMO-SYNCPOINT 
option is set for a message get request or if the MQPMO-SYNCPOINT request 
is set for a message put request. 

In transactional environments, messages are committed or rolled back in 
conjunction with other recoverable resources using the transaction manager 
two-phase (IMS/VS, IMS BMP, and all CICS environments) or single-phase 
(OS/400) commit protocol. In these environments, VisualAge Generator 
commit or rollback requests result in a commit or rollback of recoverable 
messages as well as file and database updates. 

In non-transactional environments (MVS TSO, MVS batch, IMS BMP, DL/I 
batch, VSE batch, and non-CICS environments), the only way to explicitly 
commit and back out recoverable messages is to use the MQCMIT and 
MQBACK MQI calls. An MQDISC or a normal end also results in a commit; 
abnormal termination of the region results in a rollback. The commit is a 
single-phase commit, and it is not coordinated with the VisualAge Generator 
commit or rollback functions for database. 

In the non-transaction environments, if a VisualAge Generator program 
terminates early because of an error condition that is detected by host 
run-time services, the VisualAge Generator automatic rollback does not affect 
recoverable messages, and program code cannot issue MQBACK. To ensure 
message rollback in this case, code the VisualAge Generator program as a 
called program, start the VisualAge Generator program with a call from a 
non- VisualAge Generator stub, and issue a MQBACK call in the 
non- VisualAge Generator stub if the VisualAge Generator program returns 
with a return code ^ 512 (abnormal termination detected by run-time 
services). The MQCONN and MQDISC calls should also be issued from the 
stub. 

To avoid problems with loosing messages, design workstation programs to do 
a destructive message get only after the message has been completely 
processed. 

You can use the MQCMIT and MQBACK functions in any environment. 

Handling errors 

Each MQI API function returns a completion code and reason code. In 
addition, each sample function that calls an MQI function builds a reason 
description in MQSTATE.REASON-DESCRIPTION. The reason description 
includes the API function name, the reason code in decimal, and mnemonic 
associated with the reason code in the MQSeries manuals. The reason 
description can be used in logging the error or reporting the error to the user, 
as is shown in the sample programs. 
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Specifying linkage tables for MQ programs 

On workstations, the MQ sample programs call MQ APIs via VisualAge 
Generator wrapper programs that are prelinked with MQSeries product 
libraries. In order to test or generate MQ programs, you must specify the 
linkage table appropriate for your environment and the MQSeries product 
library that you want to use. The following linkage tables are included when 
you load the sample MQ applications: 



Table 1 7. Linkage Tables for MQ Programs 



Environment 


MQSeries Library 
Description 


MQSeries Library 


Wrapper DLL 
Name 


Linkage Table 


Windows 


MQ manager 


mqm.lib 


csomqm32 


mqm32.1kg 


Windows 


MQ client 


mqic32.1ib 


csomqc32 


mqic32.1kg 


OS/2 


MQ manager 


mqm.lib 


csomqm 


mqm.lkg 


OS/2 


MQ client 


mqic.lib 


csomqic 


mqic.lkg 


AIX 


MQ manager 


libmqm.a 


csomqm 


libmqm.lkg 


AIX 


MQ client 


libmqic.a 


csomqic 


libmqic.lkg 


AIX 


MQ manager, 

threaded 

environment 


libmqm_r.a 


csomqmr 


libmqm_r.lkg 


AIX 


MQ client, threaded 
environment 


libmqic_r.a 


csomqicr 


libmqic_r.lkg 


HP-UX 


MQ manager 


libmqm.sl 


csomqm 


libmqm.lkg 


HP-UX 


MQ client 
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Testing MQ programs 

You can use the test facility to develop and test almost all MQ program logic. 
Define and debug the logic of both client and server programs using the 
VisualAge Generator test facility and local OS/2 queues. After the program 
logic is validated, you can generate for the appropriate run-time environments 
and perform the final production test with remote queues and local message 
queues. 
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If you are testing programs that commit or rollback messages, use the 
MQBEGIN function to start recoverable transactions. The MQBEGIN function 
conditionally calls the MQBEGIN API only in environments that support this 
call (Windows NT, OS/2, AIX, HP-UX, and Solaris). Because of the 
conditional call, you can leave the MQBEGIN function in programs generated 
for transactional and host environments that do not require (or support) 
MQBEGIN for starting transactions. 

When testing with MQ, make sure to specify the linkage table appropriate for 
your environment in the VAGen Test Linkage Preferences. 
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Using the Test Monitor 

Testing VAGen parts 

The test facility enables you to test programs before generating them. You can 
test a partial program, debug that part, and continue defining the program. To 
test programs, you will need to do some of the following tasks. 

Setting test preferences 

To set test preferences: 

1 . On the VisualAge Organizer window, select the Options menu, then 
Preferences. 

2. Select one or more of the following tabs to set the appropriate 
specifications. 

• Select Test to set general options and test values for EZEUSRID and 
EZESYS. 

• Select Test Linkage to specify a linkage table part and any programs 
you want bypassed when you test. 

• Select Test Trace to control what information is displayed in your trace 
log and select the type of messages displayed when you test. 

Monitoring the test 

The Test Monitor window provides textual monitoring of the current program. 

The following topics outline different ways to monitor a test. 

• Using the Test Monitor window 

• Using the Data View window 

• Using the Trace Log window 

Using the Test Monitor window 

As you run a test, information is displayed in the three panes (monitors) of 
the Test Monitor window. Initially, the Execution Stack Monitor, Watchpoint 
Monitor, and the Statement Monitor are displayed. You can display all of the 
monitors at once or just one or two of them. 

To expand and collapse monitors in the Test Monitor window, select the 
collapse button on the split bar. To hide all monitors, from the View menu, 
select Hide All Monitors. 

Each monitor displays a different kind of information. Use the following 
definitions to help you configure your view. 
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Execution Stack Monitor 

Shows the execution stack in a list. The top entry of the list is the 
name of the function that is running. Statements are displayed in the 
Statement Monitor as they are executed. The next entry in the list is 
the name of the function from which the current function was started. 
If the current function is in a called program, the functions of the 
calling program are displayed further down in the list. 

Watchpoint Monitor 

Shows the names and contents of any data elements on which you 
have set watchpoints. The contents of the data elements are updated 
dynamically as the program runs. 

Statement Monitor 

Shows the statements of a function, the flow statements associated 
with a main function, or the program components list. Each statement 
is highlighted as it rims. 

Viewing and changing data 

A Data View window presents a snapshot of the state of data elements at the 
moment you open the Data View window. The contents displayed are not 
updated. The Data View window automatically closes when the program 
resumes running. 

To open a Data View window: 

1 . From the Tools menu, select Program Data. 

2. On the Program Data window, do one of the following: 

• Double-click on an entry in the list. 

• Select an entry in the list, then select Browse. 

The Data View window appears showing the contents of the selected 
entry. 

The Data View window shows data elements, including every substructure 
level when the data elements are records. If the entry selected on the Program 
Data window is the placeholder entry for implicit data items, all the implicit 
data items in the program are listed in the Data View window. 

You can also view the contents of any data element in the current program at 
any time by doing the following: 

• From the Tools menu, select Show Data. 
Modifying data values 

To modify the contents of a data element, on the Data View window, do the 
following: 
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1 . Select a data element. 

2. Select Update. 

3. On the Move Data window, specify the new value in the Source field, then 
select OK. 

To modify the contents of a data element in the Watchpoint Monitor on the 
Test Monitor window, do one of the following: 

• Double-click on the data element in the Watchpoint Monitor. 

• From the Tools menu, select Move Data. You can do this at any time 
during the test. 

Note: You can modify only the data elements in the current program. If the 
data element you want to modify is not in the current program, you 
can use the Execution Stack Monitor to reposition the statement 
pointer to the program containing the data element. 

Using expanded view and occurrences view 

To view the complete specification, or the entire contents of the data element: 

1 . Select the data element in the Data View window. 

2. Select Expand 

The entire contents of the data element appear in the Expanded Data View 
window You cannot modify the values of the data element in the Expanded 
Data View window. 

To view all occurrences of the data element that is an array, select the data 
element; then select Occurs. 

Using the Trace Log window 

In the Trace Log window, you can view the trace entries that have been 
collected during the test. You can have any number of Trace Log windows 
open, and you can tailor each Trace Log window to display specific types of 
trace entries. 

To change the types of trace entries that are displayed, from the Options 
menu, select Set Filters. 

You can work with trace entries in the following ways: 

Saving trace entries 

To save the contents of the Trace Log window in a file, on the Trace 
Log window, from the File menu, select Save As. 

Printing trace entries 

To print trace entries, select the trace entries you want to print; then 
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from the File menu, select Print. If you want to print all of the trace 
entries, from the Edit menu, select Select All. 

Copying trace entries 

To copy trace entries, select the trace entries you want to copy; then, 
from the Edit menu, select Copy. If you want to copy all of the trace 
entries, from the Edit menu, select Select All. 

You can then copy the trace entries into a file using a text editor. 

Setting filters 

To set filters on the types of trace entries that you want to appear in 
the Trace Log window, from the Options menu, select Set Filters. 

Refreshing the trace entries 

To update the collected trace entries in the Trace Log window, based 
on the new trace entry filters you have set for that window, from the 
Options menu, select Refresh. 

Repositioning the statement pointer 

When the test is suspended, you can reposition the statement pointer to 
change the point where the test resumes. 

To reposition the statement pointer: 

• Select an entry in the Statement Monitor; then, select Confirm Reposition. 
The selected statement runs next. 

• Select an entry in the Execution Stack Monitor; then, do the following: 

1 . Select one of the statements for that entry in the Statement Monitor. 

2. Select Confirm Reposition. 

The selected statement runs next. 

To start the test over from the beginning, select Restart Test from the Options 
menu. 

Changing parts dynamically 

When a test is suspended, you can modify parts before resuming the test. 

You can make changes to parts using the Visual Age Generator editors. For the 
changes to take effect on parts being used by the test facility, from the File 
menu in the editor, you must select Save or Save As. 

At any time, you can resume the test from the point in the program where it 
was suspended. 

Once you have modified the part definitions and you want to resume testing, 
the changes you made might affect where you can resume the test. 
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In general, changes to data (data items in records and tables and variable 
fields in maps) do not affect where the test can be resumed. However, 
changes to logic (statements in functions, flow statements associated with 
main functions, and programs) can cause the test facility to automatically reset 
the statement pointer to an earlier point than where the test was suspended. 

The following list explains when the test facility repositions the statement 
pointer after changes are made to a part: 

Programs 

The statement pointer is automatically repositioned to the beginning 
of the program. If the program is a called program, the statement 
pointer is repositioned to the CALL statement that called the changed 
program. 

Functions 

The statement pointer is automatically repositioned to the statement 
where the function is first referenced in the Execution Stack Monitor. 

Maps If the changed map is currently displayed, the statement pointer is 

automatically repositioned to the start of the CONVERSE I/O option. 
The presentation of the map might not change when this happens. 

Data items, records and tables 

Generally, no change in the position of the statement pointer is 
required; however, the test facility re-initializes the data values for the 
changed part. 

Suspending a test 

A test can be suspended by one of the following methods: 
• You select the Step button 




on the Test Monitor window 

• You select the Stop button 

]E 

on the Test Monitor window 

• A breakpoint is encountered 

• A map is displayed as a result of a CONVERSE I/O option 

• An error occurs 

• The program ends 
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Resource association files 

The test facility uses a resource association file to access the files used by the 
program being tested. Generally a system administrator creates a resource 
association file for all of the developers in an organization. The following 
graphic illustrates how the test facility uses resource association files. 
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Figure 25. Resource Association File usage 



Record definitions have file names, which are logical names in the resource 
association file. Each logical name is associated with a physical file. The file 
specifications in the resource association file hold the detailed characteristics 
for the physical file. 



You can define resource associations for three file organizations: serial, 
relative, and indexed files. If the file organization is indexed, the physical file 
contains the data records and the primary index. This physical file is called 
the primary file. 



Alternate indexes are stored in other physical files called alternate index files. 
The alternate indexes are constructed on key fields in the data records that are 
usually distinct from the key field used to construct the primary index. You 
specify the offsets and lengths of the key fields when you provide the file 
specifications for the primary and alternate files. 

The following graphic illustrates the connections between alternate indexes 
and physical files: 
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Figure 26. Alternate Indexes and Primary Files 



When you use the Data File Conversion Utility to create indexed physical 
files, you do not have to use the utility to create the alternate files. If the 
alternate files do not exist when the first access is made to an alternate index, 
the alternate file for the index is built automatically. 

If you use the Data File Conversion Utility to create an alternate index file, 
only that single alternate index file is created, using the alternate index keys 
from existing records in the primary file. No other alternate files are built, 
unless you use the Data File Conversion Utility utility to explicitly create 
them. 



Setting up resource association files 

To set up a resource association file: 

1 . Determine the set of record definitions and printer map destinations that 
require resource associations. 

2. On the VAGen Parts Browser or the Test Monitor window, from the Tools 
menu, select Resource Association File. 
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Note: Creating a resource association file applies only to indexed, relative, 
and serial files, not to databases. 

3. On the Resource Association File window, do the following: 

a. To add a new resource association file to the list, select Add. On the 
Primary File Specification window, specify the logical file name and file 
specifications for the primary file, then select OK. 

b. To view and work with alternate indexes for an indexed file, select an 
indexed file entry in the list, then select Alternate Indexes. 

C. To save the resource associations in the resource association file, from 
the File menu, select Save or Save As. 

Setting up resource association files 

To set up a resource association file: 

1 . Determine the set of record definitions and printer map destinations that 
require resource associations. 

2. On the VAGen Parts Browser or the Test Monitor window, from the Tools 
menu, select Resource Association File. 

Note: Creating a resource association file applies only to indexed, relative, 
and serial files, not to databases. 

3. On the Resource Association File window, do the following: 

a. To add a new resource association file to the list, select Add. On the 
Primary File Specification window, specify the logical file name and file 
specifications for the primary file, then select OK. 

b. To view and work with alternate indexes for an indexed file, select an 
indexed file entry in the list, then select Alternate Indexes. 

c. To save the resource associations in the resource association file, from 
the File menu, select Save or Save As. 

Converting files for use in the test facility 

VisualAge Generator provides a data file conversion utility to convert data 
files that exist on host systems to a format that the test facility can use on the 
workstation. 

To convert data files: 

1 . Transfer the file containing the test data from the host system to your 
workstation in binary format. 

Note: Code points in the file on the host system should not be translated 
during the file transfer operation. 

2. On the VAGen Parts Browser or the Test Monitor window, from the Tools 
menu, select Data File Conversion. 
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Note: Converting data files applies only to indexed, relative, and serial 
files, not to databases. 

3. On the Data File Conversion window, specify the record name, source file, 
translation table name, and originating system, then select OK. 

The conversion table name is ELACNxxx, where xxx is the NLS environment 
identifier. 

Calling external programs 

The test facility requires that all external programs be installed and 
configured. This includes prerequisite programs such as DB2/2. The following 
tasks give you instructions for calling an external program from the test 
facility. 

• Using a standard call 

• Using an entry point in a dynamic link library (DLL) 

• Calling COBOL routines 

• Using an external call 

For a more detailed description of possible calls from the test facility, refer to 
the linkage table section of the VisualAge Generator Client/Server 
Communications Guide document. 

Using standard calls 

To issue a standard call, ensure that the external program: 

• Is an executable file (.EXE), a command file (.CMD), or a batch file (.BAT) 

• Exists in a directory listed in the PATH statement 

When the call is made, a new session opens and show any output. When the 
program ends, the session closes. 

Using an entry point in a dynamic link library (DLL) 

To issue a call as an entry point in a dynamic link library (DLL), ensure that 
the external program: 

1 . Contains no EBCDIC or environment characters, such as hard-coded or 
special hexadecimal characters or data fields that are in a host system data 
format. Binary fields must be in proper byte order for the environment. 

2. Has parameters that follow the C-calling conventions. 

The C-calling conventions means that the parameters are pushed onto the 
system stack in reverse order. Therefore, to call a program in a language 
that uses the PASCAL-calling conventions (which does not place 
parameters in the stack in reverse order), either the program reverses its 
parameters or the test facility calling program must reverse the order of its 
arguments on the call. 

3. Is compiled and linked in a DLL. This DLL must be in the PATH in 
Windows, or LIBPATH in OS/2. 
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Note: There is only one entry point per DLL for a COBOL program; 

however, other languages can have more than one entry point per 
DLL. 

4. Uses a linkage table that contains an entry for the program name and a 
DLL with its entry points. In the following example, the linkage table 
entries enable the programs namel and namex to be called as defined in 
the VisualAge Generator program. The dllname and entrypoint values 
specify the name of the DLL and the called program. 

: cal 1 1 i nk appl name=namel 

1 ibrary=dl 1 name 

external name=entrypoi nt 

1 inktype=dynamic. 
: cal 1 1 i nk appl name=namex 

1 ibrary=dl 1 name 

external name=entrypoi nt 

1 inktype=dynamic. 

With the linkage table entries set as above and the linkage table part name 
specified on the VAGen - Test Linkage tab, the namel program can be 
called from the test facility. 

Parameters to an external program are passed by reference. That is, an 
address is passed to the external program of the storage area of the argument 
passed by the calling program. 

Calling COBOL routines 

If you are calling a COBOL routine, consider the following: 

• Parameters are passed as pointers in VisualAge Generator. 

• Define the COBOL routine as a SUBPROGRAM. 

• In the COBOL routine, set RETURN-CODE to 0 before a GOBACK. 

• Compile the COBOL routine with the LARGE or HUGE option so that the 
program uses FAR POINTERS. 

• Link the COBOL routine with a stack size of 32000. 
Using external calls 

To setup the test facility and your environment to use External Calls, on the 
VAGen - Test Linkage tab, specify a linkage table part name. 

The CALL statement in VisualAge Generator language is interpreted by the 
test facility during the test according to the following rules: 

1 . If a linkage table entry exists for the program call, data is formatted and 
called as specified in the linkage table entry. 

2. If the named program cannot be found in the linkage table, the test facility 
searches for a .EXE, .CMD, or .BAT file to run. 

3. Control is returned to the test facility. 
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Calls to local C and COBOL DLLs are performed using standard system calls. 
As with any called program, the user needs to ensure that the called program 
is expecting data in the proper format. 

All local calls to DLLs are performed by passing pointers on the stack using 
the standard C linkage format. 

Local called programs should have an explicit BITMODE declaration in their 
linkage table entries. If an explicit declaration does not exist, a 32-bit call is 
assumed. 

Local called programs should have their parent DLL declared. If a parent DLL 
is not declared, the test facility assigns a parent DLL whose name matches the 
program name. 

If a local called program returns a value, the test facility expects a value 
between 0 and 255. If a value is not returned, the test facility continues. 

Dependencies: All local called DLLs must expect to receive the pointer array 
on the stack. Therefore, all called programs should be 
compiled with, or written so that they can be called by, 
SYSLINK linkage type (standard C linkage). Without the 
SYSLINK linkage type, the call will not succeed. All local 
called DLLs must be located in the PATH in Windows, or 
LIBPATH in OS/2. 

Other considerations: All calls to C DLLs are case sensitive. However, 

VisualAge Generator only passes uppercase program 
names. Therefore, it is required that the name of any 
program called from the test facility be in uppercase. 
DLLs must be able to be called dynamically even if 
they are meant to be bound statically. 

Binding to a relational database 

If your program uses relational databases, you must bind to the database the 
program uses. In most cases, you need not explicitly bind VisualAge 
Generator to relational databases. If an access plan does not exist for 
VisualAge Generator to use a database, VisualAge Generator can 
automatically run the SQLBIND command to create the access plan. You can 
select the desired SQL date/time format from the VAGen - SQL tab on the 
VisualAge Preferences window. This information will be used when VisualAge 
Generator runs the SQLBIND command. 

Note: To override any other options besides the date or time format, you can 
explicitly bind to the databases your program uses. Because VisualAge 
Generator acts on behalf of your program when requesting SQL 
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services from DB2/2, you must use VisualAge Generator as the 
program object name when explicitly binding to the relational 
databases. The physical file name for the bind file for VisualAge 
Generator is HPTDB230.BND. 

For detailed information on running SQLBIND, refer to your DB2/2 
documentation. 

Using breakpoints 

Use breakpoints to suspend the test at specific locations or under specific 
conditions within a program. 

You can perform the following tasks with breakpoints. 

• Setting breakpoints 

• Removing breakpoints 

• Setting qualified breakpoints 

• Enabling and disabling breakpoints 

• Encountering breakpoints 

Setting breakpoints 

You can set breakpoints at any time from the VAGen Parts Browser, Test 
Monitor, or any VAGen Editor by doing the following: 

1 . From the Tools menu, select Set Testpoints. 

2. On the Set Testpoints window, you can set a breakpoint that applies to the 
entire part or to elements of the part using the 

Q 

symbols to the left of the elements in the part. 

3. On the Set Testpoints window, the 




symbol shows that the breakpoint is an unqualified breakpoint. 
Elements that can have breakpoints 

You can set breakpoints on the following: 

• Logic elements 

- Programs 

- Functions 

- Statements 

- Logic EZE words 

• Data elements 

- Data items in records 

- Data items in tables 
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- Variable fields in maps 

- Data EZE words 

Note: Breakpoints on data items and variable fields can be set only by using 
the Set Testpoints window for the parts in which they are contained. 

Removing breakpoints 

Breakpoints remain set until you remove them. Breakpoints remain set even 
when a part is modified. 

A special case applies when breakpoints are set on statements. If you set a 
breakpoint on statement 100, delete statement 100, and save the part, then 
there is no longer a breakpoint set for statement 100. However, if you have a 
breakpoint set on the first statement in a function and you delete that 
statement and save the part, the breakpoint remains set on the first statement 
in that function. 

To remove breakpoints, you can do one of the following: 

• Remove a breakpoint individually, the same way you set the breakpoint. 

• Remove all breakpoints from the part you have open by doing the 
following: 

1 . On the Set Testpoints window, select Clear All Breakpoints. 

• Remove all breakpoints on all parts by doing the following: 

1 . On the Test Monitor window, from the Tools menu, select Remove 
Testpoints 




Remove All Breakpoints. 
Setting qualified breakpoints 

You can set a qualified breakpoint by double-clicking on the 




symbol or the 




symbol on the Set Testpoints window. 

A qualified breakpoint enables you to tailor the breakpoint to suspend a test 
when certain conditions are satisfied. On the Qualified Breakpoint window, do 
any combination of the following: 

1 . Specify a count range, using the Break On Encounter and Continue 
Through Encounter fields. 
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2. Specify a condition, using the IF Condition field. 

If an encounter value and conditional value are both specified, both must be 
true for the break to occur. 

On the Set Testpoints window, the 

symbol shows that the breakpoint is a qualified breakpoint. 
Enabling and disabling breakpoints 

You can disable breakpoints without actually removing them. Disabling all the 
breakpoints is useful when you want to control the test from the Test Monitor 
window. 

To disable breakpoints, do the following: 

1 . On the Test Monitor window, from the Options menu select Disable 
Breakpoints. 

2. To enable the disabled breakpoints, select Disable Breakpoints again. 
The 

M 

symbol appears to the right of the Disable Breakpoints menu choice when 
the breakpoints are disabled. If the 

symbol is not present, the breakpoints are enabled. 
Encountering breakpoints 

The test is suspended when one of the following occurs: 

• An unqualified breakpoint is encountered 

• A qualified breakpoint whose qualifications have been met is encountered 

The Test Monitor window shows the context of the test when the test is 
suspended. The following list describes the point at which the test is 
suspended for the kinds of breakpoints you can set: 

Logic elements 

The test is suspended before the element has run. The statement that is about 
to run is highlighted. 

Statement The test is suspended before the statement runs. 
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Program The test is suspended immediately before control transfers to 

the program using a CALL, XFER, or DXFR statement. The 
CALL, XFER, or DXFR statement is highlighted and can be 
bypassed. 

Function The test is suspended immediately before control transfers to 

the function. The statement starting the function is highlighted 
and can be bypassed. When a function is used as an error 
routine for an 1/ O function, the I/O operation has already 
performed, but the error routine has not been started. 

Logic EZE word 

The test is suspended immediately before control transfers to 
the service provided by the logic EZE word. When the logic 
EZE word is used as an error routine for an I/O function, the 
I/O operation has already occurred. 

Data elements 

The test is suspended after the contents of the element have been modified. 
The statement that caused the element to be modified is highlighted. 

Data EZE word 

The test is suspended after the contents of the data EZE word have 
been modified. 

Data item or variable field 

The test is suspended after the contents of the data item or variable 
field have been modified. 

Using tracepoints 

Use tracepoints to control the collection of trace information during a test. The 
trace entries collected provide a historical record of the occurrences during the 
test. If you require the same output from several tests, then set tracepoints 
rather than breakpoints. 

A tracepoint determines whether tracing is on or off when entering and 
exiting the part. Tracepoints take effect whenever a test is run. 

The following tasks give you instructions for using tracepoints. 

• Setting tracepoints 

• Removing tracepoints 

• Setting qualified tracepoints 

• Enabling and disabling tracepoints 

• Viewing trace entries 
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Setting tracepoints 

You can set tracepoints at any time from the following windows: 

• Any editor window 

• VAGen Parts Browser 

• Test Monitor 

by doing the following: 

1 . From the Tools menu, select Set Testpoints. 

2. On the Set Testpoints window, select the 

Q 

symbol next to the part. 

3. On the Set Testpoints window, the 

% 

symbol shows that the tracepoint is an unqualified tracepoint. 
Elements that can have tracepoints 

You can set a tracepoint on the following: 

• Programs 

• Functions 

Removing tracepoints 

Tracepoints remain set until you remove them or you close the Test Monitor 
window. 

To remove tracepoints, you can do one of the following: 

• Remove a tracepoint individually, the same way you set the tracepoint. 

• Remove all tracepoints on all parts by doing the following: 

1 . On the Test Monitor window, from the Tools menu, select Remove 
Testpoints 

a 

Remove All Tracepoints. 
Setting qualified tracepoints 

You can set a qualified tracepoint by double-clicking on the 
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symbol or the 




symbol on the Set Testpoints window. 

A qualified tracepoint turns tracing on or off upon entering and exiting the 
part containing the tracepoint when certain conditions are satisfied. On the 
Qualified Tracepoint window, do the following: 

1 . Specify a count range, using the Begin On Encounter and Continue 
Through Encounter fields. 

2. Specify a condition, using the IF Condition field. 

If an encounter value and a conditional value are both specified, both must be 
true for the trace to occur. 

On the Set Testpoints window, the 

a 

symbol shows that the tracepoint is a qualified tracepoint. 
Enabling and disabling tracepoints 

You can control how trace entries are collected without affecting tracepoints, 
by setting trace filters to collect different amounts of trace information. By 
specifying certain trace filters you are only specifying what is displayed in the 
Trace Monitor window, not what has actually been traced. If tracing is turned 
on, all possible trace entries are collected. However, the trace entries displayed 
in the Trace Monitor window are determined by the trace filters you set. 

To control how trace entries are collected during a test, on the Test Monitor 
window from the Tools menu, select Trace and one of the following: 

• Select Trace All to trace everything possible, ignoring all tracepoints. 

• Select Tracepoints Only to turn tracing on or off according to the 
tracepoints you have set. Tracing is off when the test starts. 

• Select Trace Nothing to trace nothing and ignore all tracepoints. 
Viewing trace entries 

You can view and work with the collected trace entries on the Trace Monitor 
window. You can open as many Trace Monitor windows as you need. 

A statement trace entry contains the text of the statement that runs when 
tracing is enabled. Other types of trace entries are created depending on the 
nature of the operation taking place. Sequence numbers that show the order 
in which the trace entries were collected are provided in the Trace Monitor 
window 
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To open and work with the trace entries in a Trace Monitor window, do the 
following: 

1 . On the Test Monitor window, from the Trace menu, select View Trace. 

2. If you open another Trace Monitor window, from the Options menu, select 
Set Filters to set the filters that determine what types of trace entries are 
displayed. 

3. If you want to refresh the entries that appear in the Trace Monitor window 
after selecting a new set of trace entry filters, from the Options menu 
select Refresh. 

Using watchpoints 

Use watchpoints to view the contents of selected data items, variable fields on 
maps, and data EZE words as a test progresses. Any changes to the displayed 
content of these elements are updated automatically. 

The following tasks give you instructions for using watchpoints. 

• Setting watchpoints 

• Removing watchpoints 

• Viewing the data 

• Modifying the contents of data items 
Setting watchpoints 

You can set watchpoints at any time from the following windows: 

• Any editor 

• Test Monitor 

• VAGen Parts Browser 

by doing the following: 

1 . From the Tools menu, select Set Testpoints. 

2. On the Set Testpoints window, select the 

□ 

symbols to the left of the data items or variable fields within the part. 
The 



symbol shows that a watchpoint is set. 
Elements that can have watchpoints 

You can set watchpoints on the following elements: 

• Variable fields in maps 

• Data items in records 

• Data items in tables 
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• Data EZE words 



Removing watchpoints 

Watchpoints remain set until you remove. 

To remove watchpoints, you can do one of the following: 

• Remove a watchpoint individually the same way you set the watchpoint. 

• Remove all watchpoints from the part you have open by doing the 
following: it 

1 . On the Set Testpoints window, select Clear All Watchpoints. 

• Remove all watchpoints on all parts by doing the following: 

1 . On the Test Monitor window, from the Tools menu, select Remove 
Testpoints 

El 

Remove All Watchpoints. 

Note: Removing all watchpoints from a part or from all parts enables you to 
start fresh at setting watchpoints. 

Viewing the data 

Only watchpoints set on data elements, such as data items, variable fields on 
maps, and data EZE words in the current program, are monitored. The 
Watchpoint Monitor on the Test Monitor window displays the names of the 
data elements' watchpoints that are set on and their contents. Any changes to 
the content are updated dynamically, including when the substructure or 
superstructure of the data item changes or when a data item in a redefined 
record changes. 

When a new program begins running, the contents of the Watchpoint 
Monitor changes to contain the data elements that watchpoints are set in that 
program. If no watchpoints are set in the new program, the Watchpoint 
Monitor is cleared. 

Modifying the contents of data items 

You can modify the contents of the data items in the Watchpoint Monitor by 
double-clicking on the item. 

Data items that are not displayed in the Watchpoint Monitor can be modified 
using the Data Item Editor. 

Testing Web Transaction programs 

You can test a Web Transaction program independently through ITF: 

1 . Select the Web Transaction program you want to test. 

2. Select the Test action. 
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When you test a Web Transaction program that CONVERSES a UI Record, 
ITF generates a default HTML page with all the data in the UI Record. ITF 
invokes the web browser that is registered to your operating system and 
sends the generated HTML page to the browser. 

3. Press a submit button on the generated HTML page. 

When you submit the form back to ITF, all the edits defined in the UI 
Record are run. If any of the edits fail, the page is resent to the browser 
with error messages under each field that failed its edits. If the edits 
succeed, all data is returned to ITF and the program continues on after the 
CONVERSE. At this point you can check the defined Submit Value Item in 
the UI Record for the value of the actual Submit button you pressed. 

4. Compare the UI record definition to the generated HTML page. 

At this point you can check the defined Submit Value Item in the UI 
Record for the value of the actual Submit button you pressed. 

5. View the default Entrypoint Page at the conclusion of the program. 

When the program terminates, ITF sends a default Entrypoint Page to the 
browser. The page shows all Web Transaction programs currently loaded 
in the development workspace/image that are available for testing. ITF 
simulates what occurs at run time when a program terminates by sending 
a default Entrypoint Page to the browser. During run time, the 
GatewayServlet serves the defined Entrypoint Page when a program 
terminates. 

Testing server programs 

You can use the VisualAge Generator test facility to test server programs 
running locally or on remote systems. To test a server program you must have 
a GUI client that accesses the server program and the server program must be 
loaded into the workspace/image. 

To test a server program: 

1 . Use the VisualAge Composition Editor to build a graphical user interface 
that accesses the server you want to test. 

2. Add the following statements to your linkage table: 

appl name=program name 

1 inktype=remote or 1 i nktype=csocal 1 

remoteapptype=itf 

remotecomtype=tcpip, ipc, direct, etc. 

Note: Any remotecomtype that is appropriate for the client and the server 
can be used with remoteapptype=i tf. 

3. Test your user interface. When the client calls the server, the Called Server 
Test Monitor window is displayed on the system where the server is 
running. 

4. On the prompt window, select OK to start testing the server program. 
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Dynamic Program Partitioning 

Developing distributed program systems can be complex. The individual 
programs of a distributed system must be placed onto the client / server 
machines before the system can be run. This process is known as 
"partitioning" the program system. Placing too much of a system's logic on 
the client side can result in poor performance. Ideally distributed program 
systems are partitioned to minimize communications between machines, 
which helps to achieve optimal performance. 

Dynamic Program Partitioning is a feature added to the VisualAge Generator 
test facility to assist in determining how to appropriately partition distributed 
program systems for good performance. This feature supports automatic 
default placement of GUI client, map, and database programs on machines. 
The program system can be configured dynamically during a test run, with a 
focus on communications between machines and the system constraints. The 
Dynamic Program Partitioning feature will highlight situations where changes 
are needed in the application system structure to achieve better performance. 

The Dynamic Program Partitioning feature provides a visual display of the 
interactions between programs while the application system is being tested. 
Each program is displayed as a floating icon. Programs that communicate 
extensively with each other and / or transfer a large amount of data will 
"cluster" together - that is, they will move toward one another on the display. 
This visual display is called a Clustering View. 

To take advantage of Dynamic Program Partitioning, logic should be broken 
out into separate programs. These new programs should contain no I/O. They 
will be free to "float" to the target machine where most of their interactions 
take place. This will usually result in optimal partitioning. 

Creating and using icons in the Clustering View 

The first time a call is made from one program to another, a program icon for 
each program appears in the Clustering View window. Programs that 
communicate extensively with each other or transfer a large amount of data 
will "cluster" together - that is, they will move toward one another in the 
Clustering View window. 

Note: In order to enable Dynamic Program Partitioning prior to a call from a 
client to a VisualAge Generator program, either set a breakpoint on the 
program part or select Break on Event Entry from the Test Monitor. 
Once the break is encountered, open a Clustering View window. This 
enables Dynamic Program Partitioning before the call actually occurs so 
an icon for both the client (a non- VisualAge Generator part) and the 
VisualAge Generator program appear in the Clustering View window. 
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Enabling Default partitioning from the Partitioning Setup window results in 
client, map, and database programs being placed on the appropriate target 
machines. The program system can be dynamically configured during a test, 
with focus on communications between machines, and the system constraints. 
Using the Clustering View window, situations are identified where changes 
are needed in the program system structure in order to achieve better 
performance. 

During default partitioning, target machine icons are created as needed. 

With default partitioning, map programs are automatically placed on a client 
machine icon. Database programs are automatically placed on a database 
server machine icon. Logic programs can be manually placed when they are 
called or they can be enabled to float, and then the logic programs can be 
placed after testing is complete. 

The icon representing a program identifies its type: Map, Database, or Logic 
(programs which do not contain any I/O operations). Below each icon is a 
colored label giving the name of the program. The color of the label indicates 
the number of calls received by the program. The color can range from blue 
(or "cold"), indicating few calls, to red (or "hot"), indicating many calls. The 
full spectrum of colors is shown permanently at the bottom of the Clustering 
View window for reference. 

A line is drawn between each interacting pair of programs. Think of the line 
as a spring trying to pull two programs together. The more two programs 
interact, the harder the spring tries to pull them together. The color of a line 
indicates how hard it is trying to pull the two programs together. The color 
can range from blue, indicating little pull on the programs, to red, indicating a 
strong pull. Blue lines indicate programs that are suitably positioned relative 
to the other programs, considering the amount they have interacted. Red lines 
indicate programs that are too far apart, considering the amount they have 
interacted. 

As the test runs, the system tries to reach a stable configuration. Programs 
with a strong pull (as indicated by a red line between them) tend to move 
toward one another. The line changes to a "cooler" color (that is, toward blue 
on the color spectrum) as the programs move and the amount of pull 
decreases. 

Multiple Clustering View windows can be active simultaneously. This enables 
the placing of programs in different configurations to observe system 
behavior. To add a Clustering View window, select View Clustering from the 
Partition option on the Tools menu on the Test Monitor. 
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The position at which programs finally settle relative to one another provides 
guidance concerning the machines on which the programs should be placed 
in a client / server or n-tier architecture (in order to achieve the best 
performance, given the system constraints). 

Using saved topology information 

Topology information includes details about each target machine name, 
environment, position, and so forth. When rerunning a test that has the same 
target machine configuration, you can open the clustering view based on the 
saved topology to avoid having to manually create the target machines. 

Controlling the test 

To observe the program system clustering behavior, initiate the test of the 
program from the test facility. The first time a call is made from one program 
to another, a program icon for each program appears in the Clustering View 
window. During the test, lines are drawn between programs, and programs 
will float into position around the Clustering View window. 

The test can be stopped at any point from the test facility. 
Working with programs and target machines 

Target machine icons can be added and positioned manually to define the 
distributed system. Target machine icons have an associated name, type, and 
target environment. A target machine icon can be added from the Clustering 
View menu bar by selecting Add New Target Machine from the Options 
menu. 

A program icon can be placed on a target machine icon. To place a program, 
do the following steps: 

• Select a target machine icon and program icon(s). 

• Click the right mouse button to display the program context menu 

• Select Place Programs 

Placing a program icon on a target machine icon causes the program to run 
on the selected target machine during the actual rim of the generated code on 
the distributed system. In the Clustering View window, the icon for the placed 
program will be attached to the selected target machine icon. Other programs 
will float toward or away from the placed program, but the placed program 
remains with its target machine. The pull between programs can then be 
observed. For example, a test can be run with all of the client programs 
placed on a client target machine, and all of the server programs placed on a 
server target machine. If any of the lines between the client programs and 
server programs are red at the end of the test, this indicates a performance 
problem. 
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When the programs in the distributed system appear to be placed 
appropriately, code generation can be performed for any selected program 
within a Clustering View window. 

After code for all programs has been generated, the system can be run on the 
target configuration. 

Selecting target machines and programs 

Individual target machines and programs can be selected as follows: 

• Place the cursor over the icon label 

• Click the left mouse button 

A black frame appears around the label of an icon that has been selected. 
To select more than one icon, do the following: 

• Press and hold the Ctrl key when the cursor is over the desired icon's label 

• Click the left mouse button 

A group of icons can be selected by surrounding them with a bounding box, 
as follows: 

• Place the cursor near the group of icons to be selected 

• Press and hold the left mouse button, and move the cursor 

A bounding box is formed that will follow the cursor. All icons within the box 
are selected when the left mouse button is released. 

You can deselect the icons as follows: 

• Move the cursor to a position in the Clustering View window where there 
is no icon 

• Click the left mouse button 



Using the VisualAge Smalltalk debugger 

The Smalltalk debugger in VisualAge Generator Developer is used mainly in 
conjunction with the Interactive Test Facility (ITF) to test graphical user 
interfaces (GUIs) and object-oriented scripts. 

If the Smalltalk script called by the EZESCRPT statement has an error, the ITF 
does not attempt to mask the error. Instead, the exception is caught and 
handled by VisualAge Smalltalk. The Test Montior continues to rim but is 
unusable at that time. If you can easily identify the error, you can fix the 
script error in the debugger, save the method and resume the test. If you 
cannot easily identify the problem, you should use the VisualAge Smalltalk 
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debugger to terminate the GUI client. This termination shuts down the Test 
Monitor. After you determine the cause of the error and fix it, you can restart 
the GUI client test. 

The Smalltalk debugger is invoked automatically when an exception occurs. 

For more information about the VisualAge Smalltalk debugger, see 
"Debugging your application" in the VisualAge Smalltalk User's Guide. 

Accessing VSAM files from ITF and C++ generated programs 

This section explains how to convert data for accessing OS/390 VSAM files 
from ITF and from programs generated from C++ source code. 

VisualAge Generator provides automatic ASCII-to-EBCDIC and 
EBCDIC-to-ASCII conversion for host VSAM files. VSAM files on the host 
systems are typically stored as EBCDIC characters, although you can store 
ASCII data in them as well. VSAM files on the workstation are stored as 
ASCII characters. If you use the host system just for data storage, you do not 
need to convert the data to EBCDIC. However, if you want to access the data 
from programs on your workstation and from programs on the host system, 
you need to convert the data. 

In the VisualAge Generator Preferences page, you can specify whether you 
want the data converted and what conversion table to use. Then the 
conversion happens automatically when you access OS / 390 VSAM files from 
ITF and C++ generated programs. 

Setup required to access remote VSAM files on OS/390 

For more detailed information on software prerequisites, setup instructions, 
and further details on accessing VSAM files using ITF and C++ generated 
programs, see the user's guide for the distributed file manager in SMARTdata 
UTILITIES for Windows. 

After installing the required products, configuring APPC, and verifying that 
you can establish an APPC session with your OS / 390 host, you are ready to 
configure DFM on the workstation. Following are the setup instructions: 

1 . Locate the file VSAMOS2.zip or VSAMNT.zip in the VisualAge Generator 
installation directory: installation_directory\samp\es\ 

2. Unzip the file VSAMOS2.zip or VSAMNT.zip using the following 
command: 

PKUNZIP2 -d vsamos2.zip X:\VGDFM or PKUNZIP2 -d vsamnt.zip X:\VGDFM 

where X is a drive with at least 6 MB of free space. 

3. Follow the instructions in the install. readme file in X:\VGDFM directory. 
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Note: If you have the SMARTdata UTILITIES component and Samples 

component of VisualAge installed, you do not need to unzip these zip 
files. You can use the DFM configuration files under IBM COBOL's 
samples \sdu or samples \hostdata directory. 

Accessing VSAM files from ITF 

To specify that you want to use VSAM files, do the following: 

1 . Select the Options menu on the VisualAge Organizer window. 

2. Select VAGen Preferences, and the VisualAge Preferences notebook 
displays. 

3. Select Test. 

4. At the bottom of the page, select either the Local VSAM or Remote 
VSAM radio button and click OK. 

5. Specify the VSAM translation file name if you want the ASCII-EBCDIC 
conversion done automatically. The default conversion table used is 
ELACNENU. If you don not want automatic data conversion, leave the 
VSAM translation file name empty. 

This will cause ITF to use VSAM files for all file accesses (on Windows NT, 
there is only remote VSAM file support). If you have changed your 
preferences to use Remote VSAM and you do not have the communications 
software setup and working, you will receive an error. 

In addition to changing your preferences, you also need to specify the 
physical name and path in the ITF Resource Association File editor as follows: 

1 . In the Physical name field, specify the file name as it is on your OS/390 
system but without the high level qualifier. If the file does not already 
exist on your OS/390 system, VisualAge Generator will create it for you. 

2. On OS/2, in the Path field, specify the DFM drive letter, a colon, and the 
high level qualifier specified in the DFM configuration file (config.dfm). 

3. On Windows NT, in the Path field, specify the machine name or a shortcut 
name using the Universal Naming Convention. 

Accessing VSAM files from C++ generated programs 

Access to VSAM files from a C++ generated program is determined by the 
resource association file (RSC). Specify / FILETYPE= VSAM in the ASSOCIATE 
entry for a VSAM file. Because there is no local VSAM support on Windows 
NT, all VSAM file access is remote. If you do not have the communications 
software setup and working, you will get an error. 

To access a remote VSAM file on OS/2, preface the file name with the DFM 
drive letter. On Windows NT, specify the file name using the Universal 
Naming Convention. For more information on using VSAM and resource 
association files, see the VisualAge Generator Server Guide for Workstation 
Platforms. 
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Known limitations 

• At present, OS/ 390 VSAM riles are the only VSAM files that ITF can access 
remotely. 

• When issuing a SET record SCAN with a key value of x'FFFF' or a key 
value greater than the highest record in the file, the behavior of a 
subsequent SCANBACK differs between local and remote VSAM. If 
accessing local VSAM, an I/O error will be returned instead of the last 
record. If accessing remote VSAM, the last record in the file will be 
returned. 

• Serial VSAM file "Scan" operation needs Access Mode to be set to "READ" 
only. So if you specify "READ/ WRITE" in the resource association file and 
performs "Scan" operation, you will have a hard error return code. The 
implication is that you cannot combine serial VSAM "Scan" operation 
together with other operations require "READ/ WRITE" Access Mode for 
serial VSAM file access. You will have to separate these operations out and 
change the Access Mode accordingly in the resource association file for 
serial VSAM file. 



Accessing DL/I from ITF with VisualAge middleware 

Accessing DL/I from ITF with VisualAge middleware includes the following 
steps: 

• Installing the remote DL/I component on the workstation. 

• Setting up the VisualAge remote DL/I component on the workstation and 
MVS. 

• Selecting VisualAge as the DL/I-related middleware. 

• Optionally, checking the setup status and changing the login for VisualAge 
remote DL/I. 

• Optionally, setting up tracing for the VisualAge remote DL/I component. 

• Optionally, changing the IMS batch job from the workstation. 

Installing the remote DL/I component on the workstation 

During installation, the VisualAge remote DL/I component is not installed by 
default; you need to select a custom setup. Guidance is provided by 
instructions on the install screens. 

For details on installation, see the VisualAge Generator Installation Guide. 

Setting up the VisualAge remote DL/I component 

Changes are necessary on both the workstation and MVS to support the 
VisualAge remote DL/I component. For details, see the following web site: 
http://gwareview.software.ibm.com/software/ad/vi sgen/1 i brary/dl i setup.html 
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Selecting VisualAge as the DL/l-related middleware 

To select VisualAge as the DL/I-related middleware for test time: 

1 . From the VisualAge Organizer window menu bar, click Options-* VAGen 
Preferences. 

2. The VisualAge Generator Preferences screen appears. 

3. In the left pane, click DL/I. 

4. In the right pane, under Database Access Middleware, select one of the 
following: 

• Micro Focus Mainframe Express 

• VisualAge 

If you select VisualAge, a built-in facility (if installed) provides DL/I access 
remotely on MVS, where VisualAge brings up an IMS batch environment. 

With the VisualAge option, you can access DL/I in ITF from either Windows 
NT or OS/2, even if your organization lacks an IMS Transaction Manager on 
MVS. The VisualAge option does not support a local DL/I simulation and 
does not access IMS Fast Path databases. 

For details on the other DL/I-related selections on the VisualAge Generator 
Preferences screen, see the VisualAge Generator Design Guide chapter on 
developing DL/I programs. 

Checking the setup status and changing the login for VisualAge remote 
DL/I 

If you are using the VisualAge option for remote DL/I access, you can learn 
the status of a workstation-to-MVS connection or can change the MVS login 
by invoking one of the following utilities: 

• DLICHECK verifies that the connection is working. 

1 . Go to an operating system command prompt. 

2. Type DLICHECK and press ENTER. 

3. If you have not entered a user ID and password either in ITF or by a 
previous use of one of the utilities, a dialog box is displayed; type a 
user ID and password and press ENTER. 

4. If a workstation-to-MVS connection is effect, message IWZ370I is 
displayed. Although messages are displayed if the connection fails, you 
may wish to use additional sources to help diagnose the problem: 

- Use the IBM Personal Communications APING utility to ensure that 
communications with the host have been established. 

- Review the MVS log. 
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- Perform a full IBM Personal Communications trace on CPIC-APPC 
and Token Ring communications, and in particular review the 
messages returned from MVS. 

• DLICHKP verifies that the connection is working and that a specific PSB 
can be scheduled and terminated. To invoke that utility: 

1 . Go to an operating system command prompt. 

2. Type DLICHKP and, without quote marks, the name of the PSB on 
MVS, then press ENTER. 

3. If you have not entered a user ID and password either in ITF or by a 
previous use of one of the utilities, a dialog box is displayed; type a 
user ID and password and press ENTER. 

4. If a workstation-to-MVS connection is effect, message IWZ370I is 
displayed. Although messages are displayed if the connection fails, you 
may wish to use additional sources to help diagnose the problem: 

- Use the IBM Personal Communications APING utility to ensure that 
communications with the host have been established. 

- Review the MVS log. 

- Perform a full IBM Personal Communications trace on CPIC-APPC 
and Token Ring communications, and in particular reviewthe 
messages returned from MVS. 

• DLILOGIN changes the user ID and password used when your workstation 
next connects to the remote MVS system. You specify a user ID and 
password when invoking ITF, but DLILOGIN is necessary to specify a 
different user ID and password after you start working in ITF. To invoke 
that utility: 

1 . Go to an operating system command prompt. 

2. Type DLILOGIN and press ENTER. 

3. A dialog box is displayed; you type a user ID and password and press 
ENTER. 

4. No messages are displayed to indicate success or failure (the login data 
is stored in a local cache), but you can use ITF or invoke DLICHECK or 
DLICHKP to determine whether the connection is working. 

Tracing remote DL/I calls 

If you are using option VisualAge for remote DL/I access, use environment 
variables DLITROPT and DLITROUT to trace remote DL/I calls. 

The process for specifying an environment variable depends on your 
operating system. 

• On Windows NT: 

1 . Click Start->Settings->Control Panel->System->Environment 
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2. Click on an entry in the System Variables section of the screen (to set 
variables for every user of the workstation) or in the User Variables 
section (to set variables only for the current user of the workstation). 

3. For each variable you wish to set, do the following: 

a. In the Variable textbox, type the name of the variable. 

b. In the Value textbox, type the setting. 

c. Click Set. 

4. To put the variables into effect and continue working on the screen, 
click Apply. To put the variables into effect and close the screen, click 
OK. 

• On OS/2: 

1 . Use a text editor to open the file config.sys, which is in the root 
directory of the drive in which OS/2 is installed. 

2. Add an entry of the following form: 
set van' abl e_name=vari abl e_val ue 

3. Reboot the machine. 

The environment variables for tracing DL/I calls are as follows: 

• DLITROPT specifies DL/I tracing options and can take either of two values: 

- 0, which indicates that only information on DL/I errors is retained in a 
file identified in environment variable DLITROUT. 

- 1, which indicates that information on all DL/I activity is retained in that 
file. 

The default setting of DLITROPT is 0. 

• DLITROUT specifies the file that receives DL/I trace information. If the 
value is blank or the environment variable DLITROUT is not present, 
VisualAge writes trace information to file VAGRMDLI.OUT 

If you do a typical install of VisualAge for Java, the file is in directory 
C:\IBMJava\rmtDli; the equivalent directory for VisualAge Smalltalk is 
C:\Program Files \ VAST \rmtDli (on Windows NT) and C:\VAST\rmtDli 
(on OS/2). 

The following environment variables also support the VisualAge option for 
remote DL/I: 

• RMTDLI_PARTNER_LU specifies the name of the partner LU alias and is 
set during communications setup. 

• RMTDLI_PARTNER_TP specifies the TP name of the remote DL/I server 
and is set during communications setup. 

• RMTDLI_SERVER_ENV specifies the fully qualified name of the Server 
Environment File, which is described in the next section. Do not delimit the 
file name with quote marks. 
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Changing the IMS Batch Job from the Workstation 

If you are using the Visual Age option for remote DL/I access, the following is 
true: When the test facility does its first DL/I call, the JCL in a TP profile 
starts an IMS batch environment, and that environment remains in effect until 
the user brings down the test facility. 

You can rely on the JCL in a TP profile, but you can modify it by use of the 
Server Environment File, which resides on the workstation. Invoking utility 
DLICHECK or DLICHKP also starts the IMS batch environment, and 
modifications specified in the Server Environment File are also in effect. 

Within a Server Environment File, you specify DD names, along with the 
associated dataset names that you want the Remote DL/I server to allocate 
dynamically before bringing up the IMS batch environment. If a DD name 
you specify is already in the JCL, the DD statement is an override; otherwise, 
the new DD statement is an addition. 

The syntax for specifying a DD name and an associated data set name in the 
Server Environment file is as follows: 
DD=ddname DSN=data_set_name 

Several rules apply: 

• Both the DD name and the data set name must be on the same line. 

• The data set is allocated dynamically with DISP=SHR. 

• Concatenation is supported only when the DD name is IMS. If more than 
one library is required for the IMS DD, use one line per data set. 

• The only supported DD statement parameter is DSN. 

• The only valid DSN value is a data set name. The Server Environment File 
supports neither DD DUMMY nor SYSOUT. 

An example of the Server Environment File is as follows: 

DD=RDLIDSN DSN= IMS . DATABASE. RDLI DSN 
DD=RDLIDSNO DSN=IMS. DATABASE. RDLIDSNO 
DD=IMS DSN=MYTEST. PSBLIB 
DD=IMS DSN=IMS. PSBLIB 
DD=IMS DSN=IMS.DBDLIB 

The test facility gets the fully qualified name of the Server Environment File 
from the environment variable RMTDLI_SERVER_ENV. If the environment 
variable is missing or refers to a blank or non-existent Server Environment 
file, the JCL in the TP profile is used as is. 

Note: The job that starts the IMS batch environment on MVS ends when you 
re-invoke utility DLICHECK or DLICHKP or when you close the test 
facility. 
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In relation to DLICHECK or DLICHKP, changes to the Server 
Environment File go into effect with the next invocation of the utility. 
In relation to the test facility, however, changes to the Server 
Environment File go into effect only after you have closed and restarted 
VisualAge. As a result, you can change the Server Environment File, 
invoke DLICHKP, determine that a PSB is scheduled correctly, then 
re-enter the test facility and find that the PSB can not be scheduled 
because an older Server Environment File is in effect. To end such a 
discrepancy, close and restart VisualAge. 
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Chapter 12. Generating VAGen parts 



This chapter describes how to generate VAGen parts by using VisualAge 
Generator Developer on Smalltalk. 



Setting generation preferences 

To set default generation preferences: 

1 . From the VisualAge Organizer window, select VAGen Parts^Parts 
Browser. 

2. From the VAGen Parts Browser, select Options-* Preferences 

3. On the VisualAge Generator Preferences navigation pane, select 
Generation. 

4. For code generated for the client, in the Client group box, select a 
generation options part. 

If you want code to be generated automatically when a part is saved, 
check the Generate code when saved box. 

5. For code generated for the server, in the Server group box, select a 
generation options part. 

6. You can generate server programs in batch by specifying commands in a 
generation options file. When you use the generation UI for batch 
generation, a command file is created for you that contains one of the 
following commands: 

HPTCMD Select this command if you are generating on the local 
machine. 

CALL EFKREQ 

Select this command if you are generating on a remote 
(Generation Server) machine. 

User specified Select this command if you want to specify the name of 
the program that will control generation of the selected 
parts. The program you specify must use HPTCMD or 
CALL EFKREQ commands directly or indirectly. 



Setting generation options from the UI 

You can set generation options from the user interface (UI). Each target 
environment has a set of generation options available from the generation 
options notebooks. You are not required to specify values for the generation 
options because default values are provided. 
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When NOOVERRIDE is specified for an option in the generation options 
defaults file, the field corresponding to that option is not available and the 
value defined in the default file is displayed. For details, refer to "Establishing 
default generation options" in the VisualAge Generator Generation Guide. 



Generating in batch from the Ul 

To generate in batch from the user interface (UI): 

1 . Select the VAGen part that you want to generate. 

2. Click the right mouse button and select Generate. 

3. Select Batch generation in the Generate window. The Settings button will 
be enabled. 

4. 

Select Settings. You must specify the following three values in order to do 
a batch generation for the UI: 

• Configuration map name 

• Configuration map version 

• Command file name 

For additional information on settings related to batch generation, see the 
help for the Generation Options Editor. 

5. Under Configuration map name specify the name of the configuration 
map that contains the application that contains the 4GL program and all 
its associates. 

6. Under Version specify the version of the configuration map that you want 
to use for the 4GL source. 

7. Under Command file verify or specify the path name of the command file 
that will be created. The default is image\GEN.CMD in the directory 
where Smalltalk is installed. 

8. Under Log file specify the path name of the log file. 



Generating on a LAN 

For LAN-based generation (EFKREQ is being used): 

1 . The generate command file is built. 

2. When the command file runs, it places a generation request file onto a 
queue that the Generation Server machine is monitoring. 

3. The developer's machine is thus free to do other work while the 
CPU-intensive generation task is performed by this dedicated remote 
machine. 

4. Errors are logged on the LAN. 

The following REXX programs are required to generate on a LAN: 
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• EFKREQ on the client 

• EFKSERV on the generation server 

• REXX on both the client and the server 

- OS/2 automatically includes REXX. 

- On Windows NT, you must install and set up REXX. 

The following environment variables pertain to LAN generation: 

• GENERATE_INI points to an initialization file. 

• EZERUSRID should be set to uniquely identify each machine in Novell. 

Default generation option values 

Default values are assigned to options that require a value but whose values 
have not been specified in any options files. 

For a list of valid options for each environment, see the online help. 
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Chapter 13. Developing GUIs with VisualAge Smalltalk 

This chapter describes how to develop graphical user interfaces (GUIs) with 
VisualAge Smalltalk. 

Graphical user interfaces 

A graphical user interface (GUI) program is an event-driven program that 
contains one or more windows through which program users enter data and 
request the actions performed by the program. GUI programs consist of GUI 
windows and the logic (functions) and data (records, tables) parts associated 
with the window. The GUI program calls batch or server programs to access 
files and databases. 

Defining a GUI program is different from defining character or text-based 
programs. When you develop a VisualAge Generator GUI program, you build 
the user interface visually and visually connect parts of that interface to the 
other visual and non-visual parts of the program. 

The VisualAge Smalltalk Composition Editor provides you with a parts 
palette that includes templates for creating many visual and nonvisual 
program parts. VisualAge Generator adds the following extensions to the 
VisualAge Smalltalk parts palette: 

• Additional VisualAge Generator categories and their parts 

• Additional features (such as actions, attributes and events) for parts 
shipped with VisualAge Smalltalk 

All of the VisualAge Generator extensions to the parts palette have names that 
begin with the VAGen prefix. The VisualAge Generator extensions are 
described in this chapter, along with some techniques for visual programming. 
The basic parts palette shipped with VisualAge Smalltalk is described in the 
VisualAge Smalltalk online help and the VisualAge Smalltalk User's Reference. 

For more information on visual programming and the visual parts of a GUI 
program, refer to the VisualAge Smalltalk User's Reference. For information on 
defining nonvisual parts, refer to the other chapters in this book. 

VisualAge Generator parts category for Smalltalk 

VisualAge Generator adds the following parts to the VisualAge Smalltalk 
parts palette during installation: 

• VAGen Record part 

• VAGen Table part 
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• VAGen Program part 

• VAGen Function part 

• VAGen Container Details part 

• VAGen Variable part 

• VAGen File Accessor part 

VAGen logic and data parts (records, tables, programs, and functions) are 
created and modified from the associated Visual Age Generator editors. You 
can also create a VAGen part from the Composition editor by selecting the 
part icon from the parts palette and dropping it on the free-form surface. 

To define or edit a VAGen logic or data part from the Composition Editor, 
right click on the part on the free-form surface and select Edit Part from the 
context menu or open the VAGen Parts Browser and double-click on the part 
there. 

Other VAGen parts such as the VAGen Container Details part, the VAGen 
Variable part, and the VAGen File Accessor part can only be manipulated in 
the Composition Editor. 

VAGen logic and data parts 

VAGen logic and data parts (records, tables, programs, and functions) have 
actions, attributes, and events used in connections that control the behavior of 
your program. You can change the function of GUI programs by changing the 
default properties of the parts associated with it. 

The following definitions will be helpful to you as you build GUI programs: 
Action 

a function or operation that a part can perform. Actions that are 
promoted to a part's public interface can be accessed by other parts 

Attribute 

data associated with a part. Attributes that are promoted to a part's 
public interface can be accessed by other parts. 

Event a representation of a change to a part. If a part changes, events on 
that part's public interface can be used to trigger notifications for 
other parts. 

Property 

a characteristic of a part. Part properties are displayed when you click 
with mouse button 2 on a VAGen part and select Settings. 

For more information about VAGen parts, refer to the online help. For more 
information about specific actions, attributes, events, and properties associated 
with VAGen parts, refer to the VisualAge Generator Programmer's Reference. 
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VAGen Container Details part 

Select the VAGen Container Details part to add a part that displays 
information in rows and columns, with each item occupying a row. You can 
add columns by dragging a Container Details Column part from the parts 
palette. You control the behavior of the VAGen Container Details part or the 
presentation of data it displays at run time by setting attributes, actions, and 
events for the part. 

You can use a VAGen Container Details part to display the contents of a 
VisualAge Generator Table or an occurs item of a VisualAge Generator 
Record. You can also retrieve rows in packets that can be specified in the 
VAGen Container Details part, rather than retrieving all rows at once. 

For more information on the VAGen Container Details part, refer to the 

VisualAge Generator Programmer's Reference. 

For more information on the Container Details part (Smalltalk), refer to the 
VisualAge Smalltalk User's Guide. 

VAGen Variable part 

Select the VAGen Variable part to enable your application to work with a part 
that is created at run time. A variable is a placeholder for the actual part, 
much like a parameter in an ordinary programming language. 

When you add a variable to the free-form surface, you specify its class and 
connect the variable so that, at run time, it receives its identity from a part 
elsewhere in your application. At run time, a part of that class takes the place 
of the variable. 

For more information on the VAGen Variable part, refer to the VisualAge 
Generator Programmer's Reference. 

For more information on the Variable part (Smalltalk), refer to the VisualAge 
Smalltalk User's Guide. 

VAGen File Accessor part 

Select the File Accessor part to add a part that will allow your application to 
manipulate text files. With this part, applications can read text files, display 
their contents in a string-capable control (for example, a Multi-line Edit), work 
with the actual file string, or save the string to any file and invoke the File 
dialog. Use the File Accessor part's attributes, actions, events and properties to 
control its behavior. 

For more information on the VAGen File Accessor part, refer to the VisualAge 
Generator Programmer's Reference. 
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Working with visual parts: the basics 



Creating visual parts and connections from data parts 

When you create GUI clients, a common task is to create connections between 
visual and nonvisual parts from the VAGen Data Parts category. The parts in 
the VAGen Data Parts category are the VAGen Record part and the VAGen 
Table part. This section discusses how to create connections between the user 
interface and the data representations. 

To create default visual parts associated with the data items contained in 
Visual Age Generator records or tables, complete the following steps: 

1 . On the parts palette, from the VAGen Data Parts category, select the 
VAGen Record part or the VAGen Table part. 

2. Place the part on the free-form surface. 

Note: You cannot place a nonvisual part on a visual part. 

3. On the Add Subpart window, specify the name of the record or table you 
want to add; then select OK. 

If the part exists, you can select it from the combo box. 

4. From the pop-up menu for the VAGen Record or VAGen Table part on the 
free-form surface, select Quick Form; then from the pop-up menu, select 
one of the following choices: 

• To create default controls for all of the data items in the record or table, 
select self. A Label part and a visual part are added for every data item 
in the record or table. 

• To create a default control for individual data items in the record or 
table, select the name of the data item you want to use. A Label part 
and a visual part are added for the individual data items in the record 
or table. 

Note: The data item definition determines what type of visual part is 

created. If the data item is an occurs item, a List part is created. If 
the data item has substructured occurs items, a Container Details 
part is created. 

5. Drag the mouse pointer to the visual part on the free-form surface where 
you want to place the default controls. 

If a description of the data item exists, then the description becomes the label 
for the visual part. If a description of the data item does not exist, then the 
name of the data item in the record or table becomes the label. If you change 
the description of the data item in the record or table after you perform quick 
form, the label is not updated. 
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The appropriate connections from the VisualAge Generator Developer record 
or table to the visual parts are also made for you. 

Tips on connecting VAGen parts 

Displaying VAGen data part properties: If after dropping a VAGen data 
part (record or table) on the free-form surface of the Composition Editor, no 
data item properties are displayed when you right-click on the part and select 
ConnecHAll Features, ensure that the VAGen data part has been defined and 
validated and that all shared data items have been defined and validated. 

Comparing the data and self attributes 

The data and self attributes are defined as: 

data The data attribute represents the contents of the record, table, or data 
item part. 

For an occurs item, the data attribute represents an ordered collection 
with the values of the valid elements of the occurs item. 

self The self attribute represents the part itself and contains both the data 
contents and the type description of the record, table, or data item 
part. 

For data items, the self attribute is represented by the name of the 
data item only. 

For parts other than those in the Data category, the self attribute 
represents the part itself. 

Use the data attribute of the record, table, or data item if you do not need a 
type description. 

Use the self attribute if you need a type description. The following instances 
require a type description: 

• One of the few visual parts that requires a type description is the Container 
Details part. The type description is necessary in the Container Details part 
to build column information. 

• Similar to the Container Details part, the Radio Button Set and other parts 
of the List category can be connected to the self attribute of a substructured 
data item. In this case, the Attribute Name must be set to the data attribute 
of the data item representing the List. 

• The type description is required for the request object parameter of the 
event-to-VAGenPerformRequest: action connection. 

• The type description is also used for data conversion when passing 
parameters to a VAGen Program part. 
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Tearing off an attribute 

Sometimes you might want to manipulate a part's attribute in more detail 
than the part allows. You can do this by tearing off the attribute. Tearing off 
attributes is useful when attributes are nested. It allows direct access to an 
attribute nested inside another attribute. It also allows direct access to the 
attribute's events and actions. 

To work with an attribute as if it were a stand-alone part, from the part's 
pop-up menu select Tear-Off Attribute. The mouse pointer is now loaded 
with the torn-off attribute. Add this to an open space of the free-form surface 
just as you would any other nonvisual part. The torn-off attribute appears as 
a stand-alone part connected to the original part by an attribute-to-attribute 
connection. The torn-off attribute is not actually a separate part; it is a 
variable representing the attribute. For example, you can tear off an occurs 
item or a substructured data item to access the lower level data items. 

Handling occurs items 

Data items with an occurs value greater than one are called occurs items. An 
occurs item can be substructured, but none of the data items within its 
substructure can be defined with an occurs value greater than one. 

If you tear off the occurs item, you can use it to populate a List part or a 
Container Details part. If you want to use the occurs item as if it were an 
OrderedCollection part, you must tear off the data attribute of the occurs item. 
You can then add and remove items from the List or Container Details part, 
up to the maximum number of entries that is defined by the number of items 
within the occurs item. 

Torn-off occurs data item actions: The Torn-off Occurs Data Item part has 
the following actions associated with it: 

asOrderedCollection 

The asOrderedCollection action returns an OrderedCollection of 
OrderedCollection of values of the occurs item, which can be looked at 
as a table of values. Contrast the results of this action with the 
getValuesStartingAt:to action and data attribute of the occurs data item, 
which both return an OrderedCollection of strings. 

Consider the following example, which defines an occurs data item 
called ADDRESS to have the following substructure: 

ADDRESS 

STREET 
CITY 
STATE 
ZIP 
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An asOrderedCollection action performed for ADDRESS returns an 
orderedCollection of orderedCollection of separate strings for street, 
city, state, and zip. If this result is connected to items of a Container 
Details part, the column's attribute in the column's settings view can 
be set to 1 instead of "STREET data", 2 instead of "CITY data", and so 
on. 

By contrast a getValuesStartingAt:to action returns an orderedCollection 
of concatenated strings for street, city, state, and zip. It is not possible 
to break up this result into multiple columns, unless you break the 
strings into one character for each column. 

getFieldAtlndex: 

The getFieldAtlndex: action returns the element at the specified index 
of the occurs item. You can use this action to pass the element at the 
specified index of the array as a parameter to the Callable Function 
part. 

getValueAtlndex: 

The getValueAtlndex: action returns the value of the element at the 
specified index of the occurs item. You can connect the result of this 
action to anything you would normally connect to the data attribute of 
a non-occurs item, such as a Text part's object. 

setValueAtIndex:using: 

The setValueAtlndexmsing: action replaces the value of the element at 
the specified index of the occurs item. 

getFieldsStartingAt:to: 

The getFieldsStartingAt:to: action returns elements between two indexes 
of an occurs item. You can connect the result of this action to the items 
attribute of a Container Details part to get only a certain range of the 
occurs item. 

getValuesStartingAt:to: 

The getValuesStartingAt:to: action returns the values of elements 
between two indexes of an occurs item. You can connect the result of 
this action to the items of a List part or an Ordered Collection part. 

setValuesStartingAt:to:using: 

The setValuesStartingAt:to:using: action replaces the values in the 
elements of an occurs item between a specified range using a 
specified source. The three required parameters are the two elements 
that define the range and the source for the collection. The collection 
is read from the start. 
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Consider the following example, where ItemA has an occurs value of 
10. To replace elements three through five of ItemA with the selected 
items in the list box when a push button is clicked on your window, 
do the following: 

1 . Connect the clicked event of the Push Button part to the 
setValuesStartingAt:to:using: action of the Occurs Item. 

2. Double-click on the connection to open the Settings window for 
the connection; then select Set parameters. 

3. On the Set parameters window, type 3 in the First index field and 
5 in the Second index field; then select OK. Select OK on the 
Event-to-action Connection — Settings window. 

4. Connect the selectedltems attribute of the List part to the collection 
parameter of the connection. 

When the connection fires, the first three selected items will be copied 
into ItemA at indexes 3 to 5. 

The actions for Torn-off Occurs Data Item parts are triggered when a specified 
event takes place. The get actions return information from the occurs item, 
while the set actions set information in the occurs item. 

Populating a part with Occurs Items: If you want all the items within the 
occurs item to populate the part, make an attribute-to-attribute connection 
between the data attribute of the Occurs Item and the items attribute of the 
List part, or between the self attribute of the Occurs Item and the items 
attribute of the Container Details part. 

If you want only a range of items within the occurs item to populate the part, 
do the following: 

1 . Tear off the occurs item of the VAGen Record part or the table columns 
attribute of the VAGen Table part, so it exists on the free-form surface. 

2. Make an event-to-action connection between the event you want to trigger 
the action and one of the actions for an Occurs Item, such as the 
getValuesStartingAtito: action. 

3. Set the parameters of the connection; for example, set the starting index to 
1 and the ending index to 5. 

4. Make an attribute-to-attribute connection between the result attribute of 
this connection and the items attribute of the List part or the items attribute 
of the Container Details part. 

Because the actions of Torn-off Occurs Data Item parts are triggered by 
specific events, the information in the occurs item and the visual control 
might not be synchronized. To ensure synchronization, you can make an 
attribute-to-action connection from the occurs data item to an action of the 
Torn-off Occurs Item. 
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To add or remove rows from a visual part, such as a Container Details part, 
you need to manipulate the data model, not the visual part. If the data model 
is an occurs item, you can tear off its data attribute, which is an 
orderedCollection of the occurs data. This orderedCollection can be added or 
removed using its actions, such as add: and remove:. Note that before the data 
of an occurs item can be manipulated, the occurs item needs to have an initial 
value. One way to give it an initial value is to set its record empty. 

Note: When using an occurs item, you do not get any trailing elements that 
have the default value passed on the connection, and no blank rows 
appear at the bottom of the List or Container Details. 

For more information about using occurs items, see the Programmer's Reference. 

VisualAge Generator implicit data type conversions 

The VAGen Data Parts category's data item types equate to only the following 
Smalltalk data types: 

• String 

• DBString 

• Integer 

• Fraction 

To allow the data items to be connected to attributes with other Smalltalk data 
types, such as Date, Time, and Boolean, VisualAge Generator performs 
implicit conversions on the data in VAGen data items. VisualAge Generator 
also tolerates connections that have mismatched types, when a VAGen data 
item is involved. 

For example, to enable the enabled state of a push button using a data item 
called ENABLEDITEM, you can define ENABLEDITEM as a Num data item 
with zero decimal position and connect the attribute ENABLEDITEM data to 
the push button's enabled attribute of type Boolean. To satisfy what is expected 
by the enabled attribute, VisualAge Generator implicitly converts the integer 
value of the ENABLEDITEM data attribute into a Boolean with a value of true 
or false. Without this implicit conversion, the alignment of this connection 
would cause an error. 

Besides the data parts and their data items, implicit conversions are also 
performed for VAGen Variable parts. Therefore, VAGen Variable parts should 
be used instead of VisualAge Smalltalk Variable parts to hold VAGen data 
parts and their data items. 

Implicit conversion and attribute-to-attribute connections 

VisualAge Generator implicit data type conversions handle two types of 
attribute-to-attribute connections: 
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1 . Connections that involve a data type converter, as in the connection: 
Textl (object) <--> CUSTOMERRECORD (BIRTHDATE data) 



In this connection, because the attribute object of part Textl is of the Object 
type (which is compatible with any data type), the VAGen Record part 
CUSTOMERRECORD does not perform any conversion on its attribute 
BIRTHDATE data, which is of String type. However, the Date converter of 
part Textl expects an object of type Date and would not work if it received 
an object of type String instead. Thus, the Date- VAGen converter should 
be used in place of the Date converter. The Date- VAGen converter causes 
the appropriate conversion to happen, so the string of BIRTHDATE data is 
converted to Date type before it is stored in Textl 's object attribute. 

2. Connections that do not involve a data type converter, as in the 
connection: 

Buttonl (enabled) <--> MYRECORD (BUTT0N1ENABLED data) 

In this connection, because the enabled attribute of Buttonl is of type 
Boolean, in the alignment of this connection from target to source, the 
VAGen Record part MYRECORD converts its attribute 
BUTTON1ENABLED data from its Integer type to Boolean type before 
giving the value to Buttonl. 



The following table lists the VisualAge Generator data type converters that 
should be used in place of the ones provided by VisualAge Smalltalk if 
implicit conversion is necessary. 



Use for Implicit Conversions... VisualAge 


In Place Of... VisualAge for Smalltalk 


Generator Data Type Converters 


Data Type Converters 


Boolean- VAGen 


Boolean 


Date-VAGen 


Date 


Time-VAGen 


Time 



The following table shows the default VisualAge Smalltalk data type 
associated with each VisualAge Generator data type. The table also shows the 
data type assigned to each VisualAge Generator data type during implicit 
conversion. 



Table 18. VisualAge Generator implicit data type conversions 



VisualAge Generator Data 


Default VisualAge for 


Data Type Implicitly 


Type 


Smalltalk Data Type 


Converted To 


CHA, Mixed, Hex 


String 


String 


CHA, Mixed, Hex T 


String 


Boolean, true 


CHA, Mixed, Hex '0' 


String 


Boolean, false 
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Table 18. VisualAge Generator implicit data type conversions (continued) 



VisualAge Generator Data 
Type 


Default VisualAge for 
Smalltalk Data Type 


Data Type Implicitly 
Converted To 


CHA, Mixed (see note 1) 


String 


Date 


CHA, Mixed (see note 2) 


String 


Time 


CHA, Mixed, Hex 


String 


Character 


DBCS 


DBString 


DBString 


Numeric, Decimals=0 (see 
note 3) 


Integer 


Integer 


Numeric, Decimals=0, 
non-zero 


Integer 


Boolean, true 


Numeric, Decimals-O, zero 


Integer 


Boolean, false 


Numeric, Decimals=0 (see 
note 4) 


Integer 


Date 


Numeric, Decimals=0 


Integer 


Integer 


Numeric, Decimals>0 


Fraction 


Fraction, Number 



The following notes apply to Table 18 on page 304: 

1 . The date format depends on the values of the keys 
gregorianLongDateFormat and gregorianShortDateFormat in the hpt.ini 

file. Refer to the section "HPT.INI Keys and Values" in the VisualAge 
Generator Installation Guide for more information. 

2. The time format must be HH:MM:SS, where: 

HH is a two-digit hour value (values 1-24 possible) 
MM is a two-digit minutes value 
SS is a two-digit seconds value 
: is any separator character 

3. The term Numeric represents a data item of any of the following types: 

• Bin 

• Num 

• Numc 

• Pacf 

• Pack 

4. The date format must be either YYYYMMDD or YYMMDD, where: 
YY is a two-digit year value 

YYYY is a four-digit year value 
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MM is a two-digit month value 
DD is a two-digit day value 

Implicit data type conversion examples 

Connecting to date type: To display the value of the data item BIRTHDATE 
in record CUSTOMERRECORD as a date in the text view Textl, you can use 
one of the following methods. 

• Using a CHA data item 

1 . Define data item BIRTHDATE as a CHA data item of length 8 or 10. 

2. Make the connection: 

Textl (object) <--> CUSTOMERRECORD (BIRTHDATE data) 

3. Set the data type of Textl to Date-VaGen. 

If the data item BIRTHDATE holds 1 09-3G-97 ' or ' 09-30-1997 ' , a Date of 
09-30-97 is displayed in Textl. 

• Using a Num data item 

1 . Define data item BIRTHDATE as a Num data item of length 6 or 8. 

2. Make the connection: 

Textl (object) <--> CUSTOMERRECORD (BIRTHDATE data) 

3. Set the data type of Textl to Date-VAGen. 

If the data item BIRTHDATE holds 970930 or 19970930, a Date of 09-30-97 
is displayed in Textl. 

Connecting to time type: To display the value of the data item 
CHECKINTIME in record CUSTOMERRECORD as a time in text view Textl, 
you can perform the following steps: 

1 . Define data item CHECKINTIME as a CHA data item of length 8. 

2. Make the connection: 

Textl (object) <--> CUSTOMERRECORD (CHECKINTIME data) 

3. Set the data type of Textl to Time-VAGen. 

If the data item CHECKINTIME holds the value ' 13:15:00', a Time of 
1:15:00 PM is displayed in Textl. 
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Using the 4GL parts 

Using VAGen Record parts 



Using data items 

Individual data items, occurs items, and the top-level data items of 
substructured data items appear as attributes of the record or table that you 
can use to connect to parts in your user interface. 

To access the lower-level data items of a substructured data item in a record, 
tear off the top-level data item. Consider the following example: 

Name 
ADDRESS 

STREET 

STATE 

ZIP CODE 

The only data item available as an attribute from a VAGen Record part is 
ADDRESS. If you select Tear-Off Attribute from the pop-up menu for the 
VAGen Record part, then select ADDRESS, you place the ADDRESS attribute 
on the free-form surface, making the STREET, STATE, and ZIP CODE 
attributes directly accessible. 

Using the data attribute of data items 

A data attribute is also available for the individual data items. Use the data 
attribute when you want to modify or retrieve the data of the data item. 

The data attribute of a character data item in a record is the data item's value 
without the trailing blanks. Similarly, the data attribute of an occurs item only 
holds elements that have a value different from the default value. To include 
elements that have a default value, use one of the bounding actions, such as 
getValuesStartingAtto: . 

Using individual data items 

Use the individual data item when the connection requires a data item object, 
so that the type information can be retrieved from it. 

For example, use the individual data item in the following cases: 

• When you want to pass the data item as a parameter to a VAGen Callable 
Function part. 

• When connecting an occurs item or substructured data item in a record to a 
VAGen performRequest: action. 

• When connecting a substructured occurs item to the rows attribute of a 
Container Details part. 

• When you tear off data items from a record or table. These connections are 
made for you. 
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Using VAGen Table parts 



Using data items 

Individual data items, occurs items, and the top-level data items of 
substructured data items appear as attributes of the record or table that you 
can use to connect to parts in your user interface. 

To access the lower-level data items of a substructured data item in a record, 
tear off the top-level data item. Consider the following example: 

Name 
ADDRESS 

STREET 

STATE 

ZIP CODE 

The only data item available as an attribute from a VAGen Table part is 
ADDRESS. If you select Tear-Off Attribute from the pop-up menu for the 
VAGen Table part, then select ADDRESS, you place the ADDRESS attribute 
on the free-form surface, making the STREET, STATE, and ZIP CODE 
attributes directly accessible. 

Using the data attribute of data items 

A data attribute is also available for the individual data items. Use the data 
attribute when you want to modify or retrieve the data of the data item. 

The data attribute of a character data item in a record is the data item's value 
without the trailing blanks. Similarly, the data attribute of an occurs item only 
holds elements that have a value different from the default value. To include 
elements that have a default value, use one of the bounding actions, such as 
getValuesStartingAt:to:. 

Using individual data items 

Use the individual data item when the connection requires a data item object, 
so that the type information can be retrieved from it. 

For example, use the individual data item in the following cases: 

• When you want to pass the data item as a parameter to a VAGen Callable 
Function part. 

• When connecting an occurs item or substructured data item in a record to a 
VAGen performRequest: action. 

• When connecting a substructured occurs item to the items attribute of a 
Container Details part. 

• When you tear off data items from a record or table. These connections are 
made for you. 
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Using the table column attribute 

You can tear off individual data items from a table, or you can tear off the 
table columns attribute, which represents an occurs item. When you tear off the 
occurs item, you have access to all of the attributes, events, and actions 
associated with an occurs item. 

Use the table columns attribute whenever you want to access the type 
information from a data item object, such as when you connect the table 
columns attribute of a VAGen Table part to the rows attribute of a VAGen Table 
part. 

Using VAGen Program parts 

Programs are essentially visual wrappers for what used to be the VAGen 
CALL statement that has the REPLY option set. Programs can be placed on 
the free-form surface to allow visual connections from GUI client applications 
to server applications. 

For example, you can visually code a request to read from a customer 
database by making an event-to-action connection from the clicked event of a 
Push Button to the execute action of a VAGen Program part. The VAGen 
Program part could be a VisualAge Generator called batch application which 
accepts the customer number as a parameter, reads the customer database, 
and returns the appropriate customer record. The parameters on the 
event-to-action connection can be specified visually as well. 

VAGen Program parts can be local or remote VisualAge Generator called 
applications, or local non- VisualAge Generator external programs. 

To visually program the control of logical units of work (LUW), refer to the 
descriptions of the following features: 

• VAGen commSession 

• VAGen commSessionOwner 

• VAGen inheritsCommSession 

These VAGen features are added to nonvisual parts and visual parts. For 
more information, see the Programmer's Reference. 

Using VAGen Function parts 

Consider the following example of connecting a Push Button to a VAGen 
Function part. If you make the following connections, you need to be aware of 
the order in which you make the connections: 

• Make an event-to-action connection between the clicked event of a Push 
Button and the data item of a VAGen Record part. You supply a constant 
parameter of 1 for the connection. 
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• Make an event-to-action connection between the clicked event of the same 
Push Button and the execute action of a VAGen Function part. 

The order of connections in this example is critical so that the parameter value 
of 1 is in the data item before the function is run. Thus, you must make sure 
that the data item connection is made before the function connection. Use the 
Reorder Connections From window to put the connections in the necessary 
order. 

For more information on connections, see the VisualAge Smalltalk User's 
Reference. 

Using VAGen GUI parts 

Working with VAGen Container Details parts 

Setting the columns of a VAGen Container Details part 

To set the columns, do the following: 

1 . Add a VAGen Record part or a VAGen Table part to the free-form surface. 

2. Select Quick Form from the pop-up menu of the VisualAge Generator 
part. 

3. Select a compound array item from the VisualAge Generator part and 
drop it inside the window you want. 

4. The VAGen Container Details part and columns should all be created 
automatically for you. 

Alternatively, you can set the columns as follows: 

1 . Add a VAGen Container Details part to your GUI client. 

2. Add a VAGen Record part or VAGen Table part to the free-form surface. 

3. Connect the occurs item of the VAGen Record part or the table columns 
attribute of the VAGen Table part to the items attribute of the VAGen 
Container Details part. 

4. From the pop-up menu for the VAGen Container Details part, select 
Initialize columns based on connection to #items. 

The columns are created for you from the occurs item information. 
Remember that the table columns attribute represents the data items within 
the VAGen Table part as an occurs item. The title for each column is one 
of the following: 

• The text in the Description field for the data item 

• The name of the data item, if there is no description. 

5. Remember that using a direct connection from an occurs item to any 
widget is very inefficient. You should modify the connection to use the 
getFieldsStartingAt:to: action. 
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You can select the individual columns of the VAGen Container Details part 
and delete them or drag them around with mouse button 2 to rearrange them. 

If you want to manually specify the columns of the VAGen Container Details 
part, you can go into the settings window for each column and specify the 
name of the item you want connected with the column in the Attribute name 
field. You must also add the data attribute after the name of the item. For 
example, if you have ITEM1 for columnl, you would enter ITEM1 data in the 
Attribute name field. 



Setting the contents of the VAGen Container Details part 

VAGen Container Details parts expect the object of the items attribute to be a 
compound array object. An example of a compound array is: 



Item 


Level 


Occurs 


A 


10 


10 


B 


15 


1 


C 


15 


1 



The compound array is made up of individual data items (in this example, 
items B and C). Each of the individual items corresponds to a column in the 
VAGen Container Details part. 

In this example, connect the occurs item A to the items attribute of the VAGen 
Container Details part. This causes the VAGen Container Details part to have 
ten rows and two columns (B and C). 

Each VAGen Container Details Column has an attribute name which must 
match the data attribute of the item of the items object that corresponds to the 
column. B data and C data are the attribute names for this example. 

If the VAGen Container Details part is created by doing a Quick Form of item 
A, the attribute names are set appropriately. Otherwise, you can set the 
Attribute name in the VAGen Container Details Column's settings. 

Default action 

When the user double-clicks on a row or column in the VAGen Container 
Details part, you might want an action to be performed. If so, connect the 
defaultActionRequested event of the VAGen Container Details part to an action 
in your part. 

Horizontal scrolling in the VAGen Container Details part 

A horizontal scrollbar is available for the VAGen Container Details part. 
Therefore, columns may be scrolled into view or out of view as needed. 
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Controlling the vertical scroll position in the VAGen Container Details 
part 

You can use the getTopIndex and setTopIndex: actions to find out and set the top 
row that will be visible in the VAGen Container Details part. 

Controlling the edit cell's position in the VAGen Container Details part 

Though you can get an edit cell in other selection modes, it is recommended 
that you do all direct cell editing only in the cell selection mode. Furthermore, 
you might want to set the editable state of the VAGen Container Details part to 
false if your selectionPolicy is not cell selection. You will need to drop a 
variable on the free-form surface to take advantage of these cell selection 
functions. 

When in this mode the following actions will allow you to approximate the 
function of the editCellCoordinate function in the VAGen Table part: 

getSelectedCell 

This action must be executed at least once initially to set up the 
Variable to point to a Point object. It will return a Point object with 
the (column,row) coordinate of the edit cell or (0,0) if there is no edit 
cell. Connect the result of this action to a Variable. 

endEdit 

This action must be performed to close the current edit cell. Use it 
prior to attempting to select or deselect cells. 

selectCell: 

This action takes a Point object as an argument. You can set up the 
unlisted attributes x and y of the Point Variable that you have 
initialized using the getSelectedCell attribute, by making connections to 
them from values in numeric data items. In addition to the x and y 
connections, you will need to tell the Point variable to signal itself so 
that it will be forwarded to all the connections that are using it. This 
can be accomplished by connecting some event to the self attribute of 
the Variable. Use the self attribute of the Variable as the parameter to 
the value of the connection. 

deselectAHCells 

This action can be used to unselect the edit cell. 

Selection modes 

If you have a need to switch selection modes on the fly, one easy way to do 
this is to create a menu of selection modes and connect this menu to the menu 
attribute of the VAGen Container Details part. This will then become a pop-up 
menu for the VAGen Container Details part that can be brought up with 
mouse button 2. When a selection menu option is switched, you can connect 
that action to the selectionPolicy attribute of the VAGen Container Details part 
and optionally to the editable attribute. Avoid using the readonly selection 
mode unless the editable state is set to false. 
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Understanding the cellValueChanged event 

The cellValueChanged event is a complex event that can provide quite a bit of 
information. You can set the cellValueChanged event as follows: 

1 . Connect the cellValueChanged event of the VAGen Container Details part to 
the self attribute of a Variable part. 

2. Connect the unlisted attribute row of the Variable to an Integer value. 

Note: When selecting an unlisted feature, you must enter the name 
exactly as it is described in this document. 

3. Repeat the previous step for the unlisted attribute column. 

4. Connect the unlisted attribute oldValue and newValue to appropriate values 
for the data type of the cell. 

When the event of a cell's value changing takes place, the values of the row, 
column, oldValue and newValue attributes will be returned. 

Understanding packeting 

Packeting is a function that allows a part to scroll through large amounts of 
data by asking for the next or previous set of information when needed, 
instead of getting it all up front. This requires that the traditional connection 
to the items attribute of the VAGen Container Details part from a VisualAge 
Generator table or occurs item be replaced by the following: 

1 . Connect the totalRows attribute to a number representing the total number 
of rows you will be scrolling through. This number will be used to set up 
the scrollbar correctly and it must be set before the packeting function is 
turned on for the VAGen Container Details part. 

2. Connect the packetEnabled attribute to a Boolean true value. Remember that 
this connection should activate after the totalRows attribute is set. 

3. Connect the packetRequested Event to a Variable. The Variable will get the 
following unlisted attributes: 

startRow Starting row index 

endRow Ending row index 

dataRows The Ordered Collection of rows 

Note: When selecting an unlisted feature, you must enter the name 
exactly as it appears in this document. 

4. Connect the packetRequested Event to any function that will return an Array 
of rows (for example, the getFieldsStartingAtto: of an occurs item or a 
callable function that will go against a database. 

5. For parameters to the above function, pass the startRow and endRow 
attributes from the Variable part. 

6. Connect the hasExecuted or result of the function that got the array to the 
dataRows attribute of the Variable. 
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Using VAGen File Accessor parts 



Uses for the VAGen File Accessor part 

The VAGen File Accessor part allows reading of simple text files into a string 
which can be manipulated using the String part operations or processed using 
Visual Age Generator logic. 

The VAGen File Accessor part lets you use the file selection dialog to 
determine a file specification that can be used to read a multimedia file or 
used as an argument into a called program that requires a file name (for 
example, the OS/2 System Editor). 

The VAGen File Accessor part allows editing simple text files in Multi-line 
Edit parts or other text-capable controls. 

Note: Using the read and write actions of this part for large files (>2MB), files 
that contain nulls, or files that are not easily represented as a string 
may cause unpredictable results. 

VisualAge Generator support for Reports feature 

Note: The VisualAge Generator support for Reports is not automatically 

loaded. You will need to load the VisualAge Reports feature first, and 
then load the "VAGen VA Features Support" configuration map to 
obtain this support. Please read the VisualAge Smalltalk Reports Guide 
and Reference to learn about the VisualAge Reports feature. 

The VisualAge Reports feature provides the quick report option for many 
parts, and VisualAge Generator adds the quick report option to the data items 
in a VAGen Record or VAGen Table. Quick reports are similar to the quick 
form feature used in constructing a user interface. 

Quick Report of a simple data item 

To automatically build report parts that display the data of a VAGen Data 
part's simple data item, perform the following steps: 

1 . From the pop-up menu of the VAGen Data part, select Quick Report. 

2. From the list of features, select the attribute that represents the data item. 
Note that you should select the attribute that represents the data item and 
not the attribute that represents the data item's data. 

3. Drop the generated report parts on a report line of the Report Shell. 

Example: To build report parts that display the data of data item 
CUSTOMERNAME in VAGen Record CUSTOMERRECORD, perform the 
following steps: 

1 . From the pop-up menu of the CUSTOMERRECORD part, select Quick 
Report. 
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2. From the list of features, select CUSTOMERNAME. 

3. Drop the generated report parts on a report line where you want to 
display the customer name. 

Quick Report of a compound non-occurs data item 

To automatically build report parts that display the data of a VAGen Data 
part's compound non-occurs data item, perform the following steps: 

1 . Tear off the compound data item from the VAGen Data part. 

2. From the pop-up menu of the torn-off compound data item, select Quick 
Report. 

3. From the list of features, select the self attribute. 

4. From the next list of features, select all the attributes that you want to 
display from the compound data item. Note that you should select the 
attributes that represent the data items and not the attributes that 
represent their data. 

5. Drop the generated report parts on a report line of the Report Shell. 

Example: To build report parts that display the data of data item ADDRESS 
in VAGen Record CUSTOMERRECORD with ADDRESS defined as follows: 

ADDRESS 

STREET 
CITY 
STATE 
ZIP 

perform the following steps: 

1 . Tear off attribute ADDRESS from the CUSTOMERRECORD part. 

2. From the pop-up menu of the torn-off ADDRESS, select Quick Report. 

3. From the list of features, select the self attribute. 

4. From the next list of features, select STREET, CITY, STATE, and ZIP. 

5. Drop the generated report parts on a report line where you want to 
display the customer's address. 

Quick Report of an occurs data item 

VisualAge Generator adds a new attribute called iterator to the public interface 
of an occurs item so that occurs items can be displayed in a report. The 
iterator attribute returns a read stream on the elements of the occurs item. The 
iterator, in turn, has an attribute called current, which represents the current 
element in the occurs item. In the quick report process, the iterator attribute is 
torn off from the occurs item, and the current attribute is torn off from the 
iterator, so that attributes of the current element can be directly accessed. 

To automatically build report parts that display the elements of a VAGen Data 
part's occurs data item, perform the following steps: 
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1 . Tear off the occurs data item from the VAGen Data part. 

2. From the pop-up menu of the torn-off occurs data item, select Quick 
Report. 

3. From the list of features, select the iterator attribute. Note that the iterator 
attribute is now torn off from the occurs data item tearoff and the current 
attribute is now torn off from the iterator tearoff. 

4. From the next list of features: 

• If the occurs item is substructured, select all the attributes that you want 
to display from an element of the occurs item. Note that you should 
select the attributes that represent the data items and not the attributes 
that represent their data. 

• If the occurs item is not substructured, select the self attribute. 

5. Drop the generated report parts on a report line of the Report Shell. 

Examples: 

Example 1: To build report parts that display all elements of the occurs data 
item ACCOUNTS in VAGen Record CUSTOMERRECORD with ACCOUNTS 
defined as a data item with 10 occurs and a substructure as follows: 

ACCOUNTS 

NUMBER 

TYPE 

BALANCE 

perform the following steps: 

1 . Tear off the ACCOUNTS attribute from the CUSTOMERRECORD part. 

2. From the pop-up menu of the torn-off ACCOUNTS attribute, select Quick 
Reports. 

3. From the list of features, select the iterator attribute. 

4. From the next list of features, select NUMBER, TYPE, and BALANCE. 

5. Drop the generated report parts on a report line where you want to 
display the customer's accounts. 

Example 2: To build report parts that display all elements of the occurs data 
item ACCOUNTNUMBERS in VAGen Record CUSTOMERRECORD with 
ACCOUNTNUMBERS defined as a character data item with 10 occurs, 
perform the following steps: 

1 . Tear off attribute ACCOUNTNUMBERS from the CUSTOMERRECORD 
part. 

2. From the pop-up menu of the torn-off ACCOUNTNUMBERS attribute, 
select Quick Report. 

3. From the list of features, select the iterator attribute. 

4. From the next list of features, select the self attribute. 
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5. Drop the generated report parts on a report line where you want to 
display the customer's account numbers. 

Invoking VAGen scripts from VAGen parts 

One of the best ways to signal GUI events from VAGen parts is through a 
VAGen Script. A VAGen Script is an instance method that accepts no 
arguments and is associated with the class you select when you create it. 
Using EZESCRPT you can synchronously execute code written in Smalltalk. . 
To execute a VAGen Script from a VAGen function: 

1 . Create a new visual part or open an existing one. 

2. Add a VAGen Function part to the free-form Surface, define it, and 
include a statement to execute your VAGen Script. For example: 
EZESCRPT("scriptName") 

or 

EZESCRPT(dataltem) 

Here "scriptName" is the string literal name of the VAGen Script and 
dataltem is the data item into which the script name string was moved. 

3. Add and connect the visual part that will execute the logic part. For 
example, if you are using a button, connect its clicked event to the logic 
part's execute action. 

Note: Ensure that you have selected the class to which you want to add a 
new method before you start building a VAGen Script. 

4. Create a VAGen Script with the name you specified in your logic part. You 
can type a script directly into the Smalltalk Script Editor or use the VAGen 
Script Wizard to help you compose one. 

Using the VAGen Script Wizard 

VisualAge Generator provides you with a VAGen Script Wizard that makes it 
easy for you to write simple Smalltalk scripts. Just start the VAGen Script 
Wizard and step through its instructions. To start the VAGen Script Wizard: 

1 . Create a visual part or open an existing part in the VisualAge Composition 
Editor. 

2. Select the Script Editor icon. 

3. On the Script Editor select the VAGen Script Wizard icon. 
The VAGen Script Wizard is displayed. 

As you follow the wizard's steps, the appropriate object-oriented statements 
are displayed in the Composed Script area. When you have completed the 
script, select Finish to have the method generated for you and stored in the 
appropriate object or class. 
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Understanding the VAGen performRequest: action 

You can use the VAGen performRequest: action to signal events in your GUI 
program with procedural logic. This is useful when you want to run some 
conditional logic before deciding which connection should activate. The 
VAGen performRequest: action lets you modify the behavior of a GUI program 
based on VisualAge Generator procedural logic. However, because the 
perform request action executes asynchronously using a VAGen Script is a 
better way to signal such GUI events. 

The VAGen performRequest: action is available from the pop-up menu on the 
free-form surface. 

The VAGen performRequest: action runs actions stored in its request object, which 
is a data item of a record. The request object should be a data item in a 
VisualAge Generator record with the following kind of character structure (the 
order must be exactly as defined below): 



Item 


Level 


Occurs 


Length 


PERFORMREQUEST 


10 


5 


60 


PARTNAME 


20 


1 


20 


ACTIONNAME 


20 


1 


20 


PARMNAME 


20 


1 


20 



In this example, 5 is the maximum number of actions that can be stored. The 
occurs value is the number of actions to be run. The data item and its 
sublevel items can have any valid VisualAge Generator data item names, and 
the item lengths should be large enough to hold the strings you move to 
them. The order of the sublevel items will be used to determine the 
part-action-argument connection. 



If the action you want to perform requires more than one parameter, you can 
substructure the PARMNAME data item with a data item for each parameter. 
The following table shows an example. 



Item 


Level 


Occurs 


Length 


PERFORMREQUEST 


10 


5 


60 


PARTNAME 


20 


1 


20 


ACTIONNAME 


20 


1 


20 


PARMNAME 


20 


1 


40 


PARMNAME 1 


30 


1 


20 


PARMNAME2 


30 


1 


20 
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You can also specify the occurs value of the PARMNAME data item to be 
equal to the number of parameters required by the action. However, if the 
occurs value of the PARMNAME data item is greater than 1, the occurs value 
of the PERFORMREQUEST structure must be 1. 

The VAGen performRequest: action must be connected to an event for the 
actions stored in the request object to be run when the event is signaled. An 
example of an event to use is the hasExecuted event of a VAGen Function part. 

The request object can be populated by VisualAge Generator procedural logic 
to contain the part name of the part, the name of the action to be performed, 
and the parameter that the action requires. Most actions have no parameter, so 
often this will be left blank. The part name and action name are required. 
Also, any values moved to the specific fields in this structure need to be 
placed in double quotation marks to ensure the case remains unchanged. 

To ensure that the actions do not run again the next time the event connected 
to the VAGen performRequest: action is signaled, you must blank out the 
PERFORMREQUEST request object before it is used again. 

Example using a VAGen performRequest: action 

To set focus to a Text named "Textl" in the visual part, complete the 
following steps: 

1 . Define a Record part called MYWS with the performRequest object as 
defined above. 

2. Define a Function part with the following logic. Be sure to use double 
quotation marks to ensure the case remains unchanged. 

move "Textl" to myws.partname(l) ; 
move "setFocus" to myws.actionname(l) ; 

Because the setFocus action does not require any parameters, the field 
PARMNAME can be blank. 

3. Drop the MYWS Record part on the free-form surface. 

4. On the free-form surface, make an event-to-action connection from the 
hasExecuted event of a Function part to the VAGen performRequest: action of 
the GUI program. Typically, the Function part used is the one that 
populates the MYWS Record part. 

To connect to the VAGen performRequest: action of the visual part, click on 
an open spot on the free-form surface. You are actually connecting to a 
feature of the visual part. 

5. Because the connection requires a parameter, make an attribute-to-attribute 
connection from the PERFORMREQUEST item of the MYWS Record part 
to the request object parameter. 
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Error handling 

When executing a GUI in the Smalltalk development image, if a problem is 
encountered, a walkback is produced and the Smalltalk debugger is 
automatically displayed. 

For more information about using the VisualAge Smalltalk debugger, see 
"Debugging your application" in the VisualAge Smalltalk User's Guide. 



Testing GUI clients on VisualAge Smalltalk 

The following are several important differences you will notice in the 
behavior of the VisualAge Generator Test Monitor when you use it to test 
client code that uses VisualAge Generator parts: 

• The Test Monitor is only opened when VisualAge Generator logic is 
invoked. This means that when a GUI is invoked for test from either the 
VisualAge Organizer or from the VisualAge Composition Editor the 

VisualAge Generator Test Monitor will not be opened unless the openWidget 
processing on the GUI caused VAGen logic to be invoked (as in having the 
aboutToOpenWidget action connected to the execute of a VisualAge Generator 
Function part). 

• Shutting down the Test Monitor will not affect the GUI client being tested. 
In versions prior to VisualAge Generator V3.0, when the Test Monitor was 
closed, the entire test shutdown. Now you must shutdown the GUI client to 
quit the test. If the shutdown processing invokes VisualAge Generator logic, 
then a new Test Monitor will open and run the requested logic and then go 
into "Test Complete" state when GUI client is gone. 

• When the VisualAge Generator Test Monitor is invoked for the first time, it 
is opened minimized. 

• The Break On Event Entry option is OFF by default. However, there is a 
preference on the VAGen - Test Linkage preference page that enables you 
to set it ON by default. The main point to consider is that Test Monitor will 
run continuously in the background unless one of the following occurs: 

- A User Break is invoked. 

For OS/2, this is the SysRq key. For Windows NT this is the User Break 
button on the VisualAge for Smalltalk window. 

- A breakpoint is encountered. 

- An error message is issued during processing. 

In all of the above cases, the Test Monitor will come to the foreground with 
the currently executing statement highlighted. 

• Invoking a new test session does not affect other test sessions. In versions 
prior to VisualAge Generator V3.0, each invocation of a new test would 
cause the previous test to shutdown. 
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• It is possible to get multiple Test Monitors up for the same GUI client test 
session. This can happen when you are stepping through some VisualAge 
Generator logic and you go back to the GUI and invoke either the same or 
some other piece of logic. In this case, since the first Test Monitor was 
busy a new session was opened. While it is okay for multiple Test 
Monitors to exist for independent test sessions, unpredictable results can 
occur when 2 or more Test Monitors are testing the same set of objects. 

Testing considerations for VAGen scripts 

Using VAGen scripts allows the synchronous execution of Java / Smalltalk 
scripts from within VAGen functions that are invoked by GUI clients. When 
an EZESCRPT statement is encountered in a VAGen GUI client function, test 
facility makes a "call" to a Java / Smalltalk script. Scripts that can be invoked 
this way are public instance methods (not static methods) or instance methods 
that accept no parameters and are stored on the GUI client class. Any client 
data modifications that have been made are signaled at this point and then 
the script is executed. 

Either the signalling of data modifications or the script itself can cause other 
VAGen functions or programs to execute. It is now possible for the system to 
begin execution of a VAGen event while in the middle of executing another 
VAGen event. The new event is processed and then control returns to the GUI 
client to continue either the data modifications or script execution. When the 
GUI client has completed execution of the script, control returns to the 
original function that contained the EZESCRPT statement. 

There are several important differences you will notice in the behavior of the 
VisualAge Generator Test Monitor when you use it to test client code that 
uses VAGen scripts: 

• When EZESCRPT statements trigger other VisualAge Generator logic 
events, the same Test Monitor window is displayed and the subsequent 
VAGen functions or programs are shown in the Execution Stack Monitor. 
When you use the Execution Stack Monitor to view the history of VAGen 
logic execution, you can see the original function that contained the 
EZESCRPT statement that is in the middle of processing. This behavior is 
very similar to the way function or CALL statements are handled. The 
identifier, '(from script)' is displayed at the end of the Execution Stack 
monitor entry, to show which logic events were triggered indirectly by an 
EZESCRPT statement. 

• Shutting down the Test Monitor while you are testing a VAGen logic event 
triggered by an EZESCRPT statement will not affect the GUI client being 
tested. That particular logic event is canceled, but control is returned to the 
GUI client to continue script processing. If the GUI client invokes another 
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VisualAge Generator logic event, then a new Test Monitor will open and 
run the requested logic. You must shutdown the GUI client to quit the test. 

• If the Smalltalk script called by the EZESCRPT statement has an error, test 
facility does not attempt to mask the error. Instead, the VisualAge Smalltalk 
debugger window opens with the error displayed. You can fix the script 
error and select Resume to continue the test. Control will return to the Test 
Monitor when the GUI client script is finished executing. If you close the 
debugger without resuming, the Test Monitor will be left up but will be 
unusable. You can shut down the Test Monitor yourself or it will be closed 
at a later time. If other VisualAge Generator logic events are invoked, a 
new Test Monitor will be opened. 

• If the Java script called by the EZESCRPT statement has an error, test 
facility does not attempt to mask the error. Instead, the exception will be 
caught and handled in the normal test facility manner. The Test Monitor 
will be left up, but will be unusable. You should use the VisualAge for Java 
debugger to terminate the GUI client, which will shut down the Test 
Monitor. After fixing the script error, you can restart the GUI client test. 

• If you reposition the test, or save a VisualAge Generator part that causes 
the test facility to reposition the test, while you are executing an EZESCRPT 
statement or executing logic events triggered by an EZESCRPT statement, 
the Java/Smalltalk script is canceled and no other script statements are 
executed. This means that any other VisualAge Generator logic events are 
not invoked. If the test was repositioned prior to the EZESCRPT statement, 
you can continue testing to execute the statement again and completely test 
the script. 



Generating run-time code 

Generating VAGen run-time code 

Every time you save your visual part or nonvisual part, VisualAge Smalltalk 
generates run-time code, which describes the visual parts, nonvisual parts and 
connections contained in it. If your part contains VAGen data parts or VAGen 
logic parts, the VisualAge Smalltalk run-time code contains their names but 
no other detailed information about them. To run the part, the VAGen 
run-time code has to be generated because it is this code that describes all 
data items in each VAGen data part, all statements in each VAGen logic part 
and other important information about them. 

You can specify whether or not the VAGen run-time code should be generated 
every time the part is saved. This option is on the VAGen - Generation tab of 
the VisualAge Preferences window and the default is false. You can also 
choose to generate VAGen run-time code for a part or all parts that contain 
VAGen data or logic parts in a particular application. To generate VAGen 
run-time code for a part, select Generate ■* VAGen Runtime Code from the 
Parts pull-down menu of the VisualAge Organizer. To generate VAGen 
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run-time code for all parts in an application, select Generate + VAGen 
Runtime Code from the Applications pull-down menu of the VisualAge 
Organizer. 

To specify a linkage table to be used while generating the run-time code, 
include the /LINKAGE option in a Generation Options part. Then, specify 
this Generation Options part to be used for run-time code generation. You can 
specify the Generation Options part on the VAGen - Generation tab of the 
VisualAge Preferences window if you are generating run-time code at client 
save time, or on the Generate VAGen Runtime Client Code window. 

If VAGen run-time code has been generated for a part, you can choose to test 
your parts using the run-time code and bypass the Interactive Test Facility. 
This allows you to verify your parts the way they will work at run time 
before packaging your application. This option is on the VAGen - Test 
General tab of the VisualAge Preferences window. It is important to note that 
testing using the run-time code bypasses the Interactive Test Facility for all 
parts including server programs, and you will need to already have generated 
the server programs and performed all setup needed to call them. If you are 
developing the application on Windows NT and would like to verify that it 
runs correctly on Windows 95 before packaging the application, see the 
section on building a development image with VAGen run-time support. 

You will have to generate VAGen run-time code for all parts containing 
VAGen data or logic parts before you can successfully package your 
application for run time. If a part's VAGen run-time code is missing or 
contains changes that require generation, you will get a packaging error. 

While generating VAGen run-time code any table parts that are on your visual 
part or nonvisual part will automatically be generated by default. If you do 
not wish to generate the tables along with the run-time code, specify the 
/NOGENTABLES option in a Generation Options part and select this options 
part to be used when generating the run-time code. 

When the table is generated, the default conversion table that will be used 
will be based on the platform (OS/2 or WINNT) that you are generating on. If 
you chose to have the tables generated along with the run-time code, you 
should ensure that the platform on which you are generating is the same as 
the platform on which you will be packaging and executing. The default 
conversion table names are specified in the HPTRULES.NLS file. 

Iding a development image with VAGen run-time support 

If you choose to verify that your application runs correctly on either Windows 
3.1 or Windows 95 before packaging it for run time, you will need to build a 
development image with VAGen run-time support. To build this image, you 
will need to complete the following steps: 



Chapter 13. Developing GUIs with VisualAge Smalltalk 323 



1 . Install the image file installed with VisualAge for Smalltalk Pro connected 
to a library manager that contains VAGen features. 

2. Install VisualAge Generator Common Services. 

3. Copy the VisualAge Generator run-time files. 

4. In the VisualAge for Smalltalk Pro image, you will need to load the 
configuration map VAGen VG Client Runtime and the applications that 
contain the parts to be verified. Testing the parts in this image is 
equivalent to testing them in run-time mode in the image that has VAGen 
Developer loaded. 

The following scenario provides an example of the tasks you might have to 
perform: 

• On a Windows NT, Windows 95 or other workstation, install VisualAge for 
Smalltalk Pro - Manager Library 

• On the Windows NT machine, complete the following steps: 

1 . Install VisualAge for Smalltalk Pro - Client, which points to the 
Manager Library installed previously 

2. Install VisualAge Generator Developer and VisualAge Generator 
Common Services 

3. Start VisualAge for Smalltalk Pro - Client 

4. Load VisualAge Generator features 

5. Develop your application and test it 

6. Generate VAGen run-time code for all parts in your application 

7. Version and release your classes and application 

• On the Windows 95 machine, complete the following steps: 

1 . Install VisualAge for Smalltalk Pro - Client which points to the Manager 
Library installed previously 

2. Install VisualAge Generator Common Services 

3. Copy the VisualAge Generator run-time files 

4. Start VisualAge for Smalltalk Pro - Client 

5. Load the configuration map VAGen VG Client Runtime 

6. Load your application 

7. Test your application 



Packaging run-time code 

This section covers a number of issues you should consider when you 
package run-time code. For more information on IC packaging, see "Image 
component packaging" on page 327. 

Packaging considerations 

When packaging your application as an executable, all classes and scripts that 
are used in the application need to be included or you will receive a run-time 
error when the class or script is accessed. Classes or scripts are included in 
the packaged image if they are referenced directly in your parts or in your 
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scripts. However, if you use the Object Factory Parts or View Wrappers where 
the viewPartClass attribute is set dynamically or you make indirect references 
to classes in your scripts there are no direct references to the classes to be 
opened with the Object Factory Parts or the View Wrappers; therefore, they 
will not be included in the packaged image.In addition, scripts that are not 
invoked directly via a visual connection but are invoked via the EZESCPvPT 
statement from a VisualAge Generator function are indirect references; 
therefore, they will not be included in the packaged image. 

To ensure all classes your application needs are packaged, add a class script 
called packagerlncludeClasses to the class that has the same name as your 
application. 

Example: 

• Your application is MyApp 

• It includes these visual parts: 

- Main View 

- Subsystem Viewl 

- Subsystem View2 

- Subsystem View3 

• Main View contains an Object Factory Part that will be asked to create 
Subsystem Viewl, Sub System View2 and Sub System View3 at run time 
depending on the options that the end-user selects. 

• To ensure that Subsystem Viewl, Subsystem View2 and Subsystem View3 
classes are included when MyApp is packaged, add the class script 
packagerlncludeClasses to MyApp class as shown in this example: 

packager I ncl udeCl asses 

(Set new 
add: SubSystemViewl; 
add: SubSystemView2; 
add: SubSystemView3; 
yoursel f) 

To ensure all scripts your application needs are packaged, add a class script 
called packagerlncludeSelectors to the class that has the same name as your 
application. 

Example: 

• Your application is MyApp 

• It invokes the following scripts via EZESCRPT: 

- scriptl 

- script2 
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• To ensure that scriptl and script2 methods are included when MyApp is 
packaged, add the class script packagerlncludeSelectors to MyApp class as 
shown in this example: 

packager I ncl udeSel ectors 
"#(scriptl 

scn'pt2) 

Distributing for run time 

Refer to the section "Distributing your application" in the VisualAge Smalltalk 
User's Guide for the list of files to distribute for run time. You will need the 
following files: 

• abtrules.nls 

• rgb.txt 

• VisualAge Generator Common Services 

• VisualAge Generator run-time files: 

- hptrun45.dll (one for OS/2 and one for all Windows platforms) 

- hptrules.nls (one for OS/2 and one for all Windows platforms) 

- HptGB.cat (for translated national languages) 

- HptCX.cat (for translated national languages) 

• Any generated table parts (tblname.TAB) used by the views 

The following notes are true for all VisualAge for Smalltalk and VisualAge 
Generator files: 

• .MPR files and .NLS files need to be in the directory pointed to by 
"nlspath" of the .INI file or in the directory where the application is started 
from. 

• .DLL files need to be where the operating system can find them (i.e. On 
OS/2, a directory in the LIBPATH (and on Windows, a directory in PATH 
or current directory). 

• Other files need to be in the directory where the application is started from. 

If you have packaged multiple applications to run, and would like to keep the 
application files in separate directories but would like to share common files, 
you can do the following: 

1 . Create a common directory that holds all required VisualAge for Smalltalk 
files and VisualAge Generator files. 

2. Add this directory to your LIBPATH on OS/2 or PATH on Windows. 

3. Create subdirectories for the applications that hold the executable, .INI file 
and run-time image file for each application. 

4. Update the nlspath in the application's .INI file to point to the common 
directory. 

5. Start the application from its directory. 
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Image component packaging 

This section describes the VisualAge Generator Automated IC Packaging 
mechanism. The mechanism is based on the image component (IC) technology 
available within VisualAge Smalltalk, on which VisualAge Generator (VAGen) 
GUI development environment is based. For more detailed information about 
image components (ICs), please consult Chapter 36, Packaging with Image 
Components (ICs) of the IBM Smalltalk User's Guide (SC34-4773-00). 

The Automated IC packager in VAGen is designed to simplify the task of 
building ICs as well as providing a mechanism for dynamically loading ICs as 
needed at run time. The latter functionality is not provided by VisualAge 
Smalltalk and you are expected to manage any dynamic loading of your ICs 
yourself. However, this VAGen extension takes care of that programming task 
for you. 

The following information is available for VAGen GUI developers using 
VisualAge Generator version 4.0 or later, the IC packaging mechanism, and 
the reduced run-time packaging mechanism. The reduced run-time packaging 
mechanism is the output of the Make Executable menu option, initially 
provided in VisualAge Generator version 3.0. 

Introduction to ICs 

The IC delivery mechanism combines technology initially provided in 
VisualAge Generator version 3.0 with a packaging and delivery mechanism 
that is more reminiscent of app files that were used to build GUI applications 
prior to VisualAge Generator version 3. ICs represent image components, 
hence the name. Rather than a single, large loadable .ICX file that contains 
your VAGen GUI code, ICs provide a partitioning mechanism that allows 
your application to be split over multiple files (with suffix .ic). For VAGen 
GUI applications, every GUI screen can potentially be packaged into a 
separate file. ICs provide the following benefits for VAGen GUI developers: 

• ICs reduce run-time application memory requirements by only loading into 
memory those GUI portions of the application that are used in the 
particular session 

• ICs aid in incremental deployment of large applications containing many 
views. Also, code corrections in individual views would not require a 
complete redeployment of the application code. 

• ICs allow adding new GUI functionality to the application in an 
incremental manner 

There are three types of ICs that are output as the result of the VAGen 

automated packaging: 

Prerequisite Components 

An IC that contains code that is shared with more than 1 view in 
more than 1 ENVY application. If another IC directly references a 
class in a prerequisite component, then the prerequisite component is 



Chapter 13. Developing GUIs with VisualAge Smalltalk 327 



loaded before the component where the reference is made. Typically, a 
prerequisite component contains shared GUI forms that are used 
within many different views within your application. 
Loadable Components 

A loadable component is one that is dynamically loaded when a 
symbolic reference to a class name contained within the loadable 
component is resolved. Within a loadable component, code should 
only contain direct class references to classes that: 

• Are defined in the same application where they are referenced 

• Are defined in a prerequisite component. 

Typically, a loadable component contains one or more view classes 
that imbed shared forms and reference other views using 
ViewWrapper, Object Factories, or Variable parts. Using one of the 
latter parts is considered an indirect class reference as opposed to a 
direct reference to a class. A script or a directly embedded part is an 
example of a direct reference to a class. 
Launch Component 

The output of the automated packaging process includes a special IC 
called the launch IC. The launch IC contains information about the 
contents of the other ICs produced in packaging, so that it can control 
the dynamic IC loading process. The launch IC also contains the name 
of the first view to be opened when your application is started. None 
of your application code is packaged into the launch component. 

To successfully make use of VAGen loadable components, it is important to 
analyze your existing VAGen GUI classes and applications and ensure that 
they conform to the above constraints for prerequisite and loadable 
components. 

Preparing ENVY applications for VAGen ICs 

Before you migrate your non-IC application to use VAGen ICs, it is critical 
that your ENVY application prerequisites are set up properly and that all class 
references are properly scoped. For VAGen GUI programming that does not 
use Smalltalk scripting, a class reference usually implies an imbed. An imbed 
is a Form that is placed on one of your views in the Composition Editor. A 
class reference is properly scoped if the class being referenced resides in the 
same application as the referencing class or if the class being referenced 
resides in a prerequisite application of the application defining the referencing 
class. 

Steps for ENVY application preparation 

You should save your image each time you make major changes to large 
numbers of classes and applications. 

1 . Ensure that your ENVY application prerequisites are correct for reduced 
run-time packaging. Can you successfully package a reduced run-time 
image? If not, you should correct any packaging problems by changing 
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ENVY application prerequisites or moving classes between different 
applications. Refer to chapter 9 - Packaging your Visual Age Application in 
the VisualAge for Smalltalk User's Guide (SC34-4772-00) for more 
information on packaging a reduced run-time image. It is critical that you 
complete this step before proceeding. 

2. With your VAGen GUI code loaded into the image, examine your code 
and partition it into ENVY applications to satisfy the following criteria: 

a. For VAGen GUI ENVY applications that contain both GUI Visual Parts 
and 4GL part class extensions (e.g. VAGenRecords), separate out the 
4GL class extensions into one or more separate ENVY applications. 
VAGen parts are development time parts. Development time parts are 
not used at run time. If VAGen parts are left in the same ENVY 
applications as GUI Visual Parts, then the produced ICs are larger than 
necessary. The 4GL part class extensions will occupy memory when 
loaded because IC packaging does not reduce (remove code from) ICs. 
Either move all of the VisualAge Generator part extensions to a 
common application, or split each GUI application into development 
and run- time portions. 

b. Identify applications that contain imbedded Visual Parts. An example 
imbedded Visual Part is a reused Form. These classes must go into an 
application that is built as a prerequisite IC rather than a loadable IC. If 
necessary, move these shared Forms into a common application that 
can be shared by other applications that make use of the form. If a 
form is only used in a single imbed and it resides in the same ENVY 
application as the view that uses it, it does not have to be moved. 

3. Save your image 

Migrating VisualAge Generator GUI applications to use ICs 

Before attempting to package ICs, you must migrate your existing VAGen 
GUI applications so that they will work both with the IC dynamic loading 
mechanism as well as in a reduced run-time image. 

Steps for application migration 

1 . If you have never saved your GUIs or regenerated the run-time code on 
the new Smalltalk base (V5.0), you must regenerate the run-time code 
(VisualAge Organizer^ Applications->Generate^Runtime Code) on all your 
Envy applications that contain the GUIs you wish to package. This adds a 
new method to each GUI class (called abtUntranslatedConstants) that 
contains the non-NLS enabled string constants in your GUIs. This method 
is required for automated IC packaging to work. However, once it exists 
you should not have to repeat this step. 

2. Save your image. 

3. Generate the run-time code (VisualAge 

Organizer-* Applications^Generate^ VAGen Runtime Code) on all your GUI 
applications to ensure that your application includes the most up to date 
4GL member definitions. This step only regenerates code if needed so it is 
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always a safe and important thing to do before packaging. If you change 
record structures that you use to send data over to your 4GL server 
programs you might need to regenerate your 4GL server programs as well. 

4. Save your image. 

5. Run the migration utility (Visual Age 

Organizer^ Applications^Migrate^Enable for VAGen IC Packaging) to 
migrate the GUI applications for VisualAge Generator IC packaging. This 
migration updates the #abtBuildInternals methods on all your Visual Parts. 
It replaces ViewWrappers, Object Factories, and AbtVariable parts with 
equivalents that will operate correctly using the dynamic IC loading 
mechanism. 

6. Save your image. 

7. Run the out of scope references tool (Transcript-* Tools ->Query->Out of Scope 
References...) on all your applications. This utility flags direct references to 
classes that are not in the prerequisites of the application where the 
reference occurs. Correct any problems by moving classes to different 
applications or changing your application prerequisites. 

8. Version and release your classes and applications 

9. Save your image. 

When you have reached this point, you are ready to set up the mappings that 
define the ICs that are created as part of the IC packaging process. You should 
identify the view class that is first opened when the GUI runtime executes. 

Defining a Component Manager mapping 

Set up the component manager for ALL your ENVY applications, even if you 
do not plan to package all your ICs right away. It is very important that ALL 
the ENVY applications that your system comprises be defined or packaging 
might not proceed correctly. To set up your initial component mapping, select 
the application that contains your start-up view, then the menu item 
VisualAge Organizer^ Applications->Make Component Executable, as shown in 
Figure 27 on page 331. 

You can load the IC Packaging sample to demonstrate how automated IC 
Packaging is used. This sample is contained in a file called ICPKGS.DAT. For 
instructions on loading samples, see the appendix in VisualAge Generator 
Getting Started. 

Note: You can have only one component manager mapping loaded in the 
image. When you are ready to package your application, you should 
unload the sample or extend the sample component manager mapping. 
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Figure 27. Invoking the Component Manager Utility 

If no mapping exists in the image, you are presented with the Make 
Component Executable dialog shown in Figure 28 on page 332. From this 
dialog, you should select the view class that is the initial one displayed when 
your application is started. In the figure, the view ICGUI1 is specified as the 
initial view. 
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Figure 28. Specifying the initial view 

Once the initial view has been selected, the Component Manager view is 
displayed, as shown in Figure 29 on page 333. This view provides you with 
the mappings required by the IC packager. Based on your initial start up view 
selection, the Component Manager will automatically fill in component 
mappings for your ICs using default names and mappings. By default, each of 
your applications are packaged into a separate IC. Selecting a particular 
component will display the list of applications that are to be packaged into 
that component in the lower area marked applications. For each component 
entry, the component name, type, resulting file name and packaging sequence 
are displayed. 
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Figure 29. Component Manager view 

To change the details of a particular component mapping definition, select the 
component and press the Change button (or double-click on the component). 
The displayed result is the Component Properties dialog, as shown in 
Figure 30 on page 334. 
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Figure 30. Changing component properties 

From the Component Properties view you can change four aspects of the 

component: 

Component Name 

The name used for identification purposes. It is solely used during 
development and packaging. Specify any name here that is 
meaningful and best describes the IC. 

Type The most important of the component properties. The drop down list 
allows a selection of Prerequisite or Loadable. By default, all the 
components are set to Loadable. Automated IC packaging cannot 
accurately determine which components should be Prerequisite 
components and which should be Loadable components - the 
developer must review the list and specify the correct component type 
for each component. If the component contains only applications with 
shared, reused GUI classes (e.g., imbedded Forms), then the 
component type should be changed to Prerequisite. 

IC Filename 

The name of the IC file that is packaged. It must conform to DOS 8.3 
style naming conventions. 
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Applications 

The list of applications that are contained in the IC. By default, each 
component is set up to contain only one application. 

Note: The same application cannot be loaded into the virtual machine 
more than once. If you change the included applications and 
you intend to load two separate ICs into a run-time image, do 
not inadvertently package the same application into the two 
ICs. 

The result of changing the components for our example is shown in Figure 31 
on page 336. The component containing the Application IC Sample Common 
Parts IC has been changed to a Prerequisite component. The components have 
been given meaningful names that correspond to the functionality that they 
include. The file names have been changed to correspond somewhat to the 
component name. You may sort the entries in the Components container by 
clicking on the column heading. Name and icName sort alphabetically, while 
Type sorts in the order prerequisite, loadable, launch. Seq (Sequence) sorts by 
order of packaging so that you can determine the order in which the 
components are generated. 
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Figure 31. Component Manager view after editing components 

There is special component named Launcher. This IC is the one that is 
responsible for starting up the system, launching the view that was specified 
and managing the dynamic component loading mechanism. Double-clicking 
on the Launcher component produces the dialog shown in Figure 32 on 
page 337. The Component Properties for the launch view is slightly different - 
it allows you to change the selected start-up view, IC name and filename, but 
not the IC type. 



336 VisualAge Generator: User's Guide 



r-- Component Pioperties 



Name: 
Type: 

IC filename: 



IC Sample Launcher 



Launch 



~3 



icsamp.ic 
Select view to open on startup 




□ K Cancel 



Figure 32. Launch IC definition 

After all the component definitions have been set up, pressing the Save button 
on the Component Manager view will save the component definitions. You 
are asked for an application into which to save the definition, as shown in 
Figure 33 on page 338. You can specify an existing application or a new one. It 
is recommended that you specify a separate application, for ease of 
management purposes. Saving the Component Manager will cause the 
Smalltalk method #default to be extended on the class 
HptComponentManager. This means that only one Component Manager 
definition can be present in your image at any time. Saving the Component 
Manager to a separate application allows for greater flexibility. The new 
HptComponentManager class extension should be versioned and released, 
and the new application should also be versioned. This allows you to keep a 
version history of changes to the application IC mapping, especially if you are 
undergoing development where new applications are added as new ICs over 
time. 
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Figure 33. Saving the Component Manager definition 



Packaging ICs and creating an executable 

Note: If you want to test out only a portion of your VisualAge Generator GUI 
application, please read the section Packaging A Subset of your GUI, 
prior to packaging. 

To create an executable for your application, from the Component Manager 
view, press the Make Executable button on the center bottom. Depending on 
the number of loadable components that have to be repackaged, and the 
processor speed of the machine doing the packaging, this process can take 
anywhere from several minutes to several hours. On subsequent repackaging, 
the automated IC packager will automatically determine the minimal set of 
ICs that needs to be repackaged. You are prompted for the name and 
directory location of an executable to be produced. It is strongly 
recommended that you specify an empty folder or directory to hold the 
output of the packaging process. 

During packaging, a progress dialog will indicate how many ICs are to be 
packaged as well as the number of ICs packaged so far. Log output from 
packaging is directed to the System Transcript. The log output will specify 
each component that has been packaged, the time taken to package the 
component and any packaging errors that were encountered while packaging. 

Make Executable will produce several artifacts in the directory that you 



HptRun directory 

The directory that contains the .ICs just packaged for your application 
as well as the VisualAge ICs required by your application to function 
correctly. 
Nls directory 

The directory that contains the .MPR and .CAT files associated with 
the VisualAge ICs in the HptRun directory that are required for your 
application to function correctly, 
.exe The .exe used to run your application. The name of the file is the 



specified: 
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name you specified in the prompter just after the Make Executable 
push button was pressed. The name is the same as the .exe file name 
(without the extension) 
.ini The .ini file that directs the VisualAge virtual machine to load IC files 
from a particular directory - in particular the HptRun directory 
described above. 

.icx The start-up image used by the .exe. The name is the same as the .exe 

file name (without the extension) 
cursors.obj 

The cursors file used by VisualAge Generator 
rgb.txt The color map file used by VisualAge Generator 

You must also first install all the files required by VisualAge for Smalltalk for 
the run-time platform you are running. The list of these files can be found on 
the VisualAge for Smalltalk web page 

(http: / / www.software.ibm.com/ad / Smalltalk/ support/ tips50.html). 

It is assumed that the structure of the directory produced matches the one 
that is delivered to the run-time environment. 

Note: The .ini is sensitive to its directory location. If you move or reorganize 
the output directory then the .ini file should be reviewed and changes 
made to reflect the changed directory structure. 

To run the resulting application, invoke the .exe file from a DOS prompt or 
shortcut, within the directory that it resides. 

Handling class references in Smalltalk scripts 

The migration step you performed to prepare your application for use with 
ICs assumes that you did not write any custom Smalltalk scripts that contain 
direct references to views. The migration process only updates the 
#abtBuildInternals method on each view and it will only update references to 
views that occur through Variable parts, Object Factory parts, and View 
Wrapper parts. Any other class or view references that occur in applications to 
be packaged in loadable component ICs must be symbolic rather than direct 
class references. 

Direct references to classes in loadable components can be modified by 
substituting the following code where the class reference originally appeared: 
IClassName hptAsPartType 

Note: This code will work with either a VAGen IC image or reduced run-time 
image. 
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Troubleshooting 

The following scenarios are discussed: 

• IC's size too large 

• Run-time debugger when starting up initial view 

• Cannot start .exe 

IC's size too large 

Typical IC sizes containing views range from 10s of k to a couple of 
megabytes. If the packaging process produces ICs that are significantly larger 
than this, this is typically caused by missing defined applications in the 
HptComponentManager setup. Ensure that you have included IC mappings 
for all your ENVY applications in the HptComponentManager, even if you 
only plan to package a subset of the ICs. 

Run-time debugger when starting up initial view 

The view you specified as the initial start-up view must be in an application 
that is to be packaged into a loadable component and cannot be packaged 
into a prerequisite component. 

Cannot start .exe 

If you receive the error dialog "Exit due to error: 37 - Image file is not an 
image" when you run your application, you should run the application from a 
DOS prompt and specify the command line option: 
-l<logfile.txt> 

which instructs VAGen to output information messages to the specified log 
file. Examine the log file for the reason that the launch failed. In many 
circumstances, the start-up will fail because of a timestamp mismatch, which 
looks like this: 

'myApp.ic' timeStamp mismatch. Exit due to error: 37 - Image file is not an image 

This often is the result of a prerequisite component being packaged after the 
loadable components that depend on it. The loadable components are 
dependent on code in the prerequisite component, but the code in the 
prerequisite component has changed. This leaves the system in an inconsistent 
state. The most prudent approach to correcting this situation is to repackage 
all your ICs. To do this, you must: 

1 . Go to the VAGen directory (where abt.exe) is installed and delete all the 
files ending in .ic. 

2. Delete all the files ending in .snp. 

3. Re-run Make Executable 

Deleting the files will force the system to recalculate the timestamps 
associated with the files and should put your system back into a consistent 
state. 

TimeStamp mismatch during packaging 
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If you installed a patch to the base Smalltalk code in your system (e.g. if you 
installed a fix you downloaded off of the VA Support web site), and this patch 
affects code at run time, you may not be able to package your ICs 
successfully. This is because the base ICs that you installed along with the 
product were not built with this patch in them so your development and 
run-time systems are no longer consistent. To be able to successfully package 
your ICs, you would either have to remove the patch you installed by 
reloading the last official version of the ENVY application that contained the 
patch into your image or you will have to rebuild the base product IC that 
includes the affected ENVY application and any dependent base ICs prior to 
attempting to build your own application ICs. Call the IBM support center if 
you need assistance with building these base ICs or if you need to figure out 
which base ICs need to be rebuilt. If IBM ships an official fixpak that includes 
a set of replacement ICs that match the patches you previously installed, then 
you might not need to unload these patches any longer. 

Please review the VisualAge Generator readme document for any special 
instructions regarding patches that are shipped preinstalled in the product 
that you may have to uninstall before attempting to package your system 
using ICs. 

Note: Always ensure that the output directory for Make Executable is a 

directory other than the VAGen directory (the one containing abt.exe). 

Working with VAGen automated IC packaging 
Packaging a subset of your GUI 

The component manager allows for selective packaging of components. You 
can use this facility when first enabling a VAGen GUI application with a large 
number of views and applications, to test out an initial view subset. 

1 . Follow all the application and code preparation steps described in the 
Getting Started section above. 

2. Define all your Component Manager Mappings. Specify your start-up 
view. Based on our example, the Component Manager view would look 
somewhat like that presented in Figure 34 on page 342. 
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Figure 34. Packaging selected components 

3. Package those loadable components that contain the views that you want 
to test. Sort the components by name, if you know the name of the 
components that you wish to package. Multi-select these components 
(using the Shift and Ctrl keys in combination with the left mouse button) 
and then press the Package button. The Package button will limit 
packaging to those components you have selected (and their prerequisite 
components). Using the Package button only produces the IC files - it 
does not produce an .exe or other files that are produced when using the 
Make Executable button. Examine the Transcript for possible packaging 
problems. 
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4. Package your launch IC. Sort by Type and the launch IC will appear at the 
bottom of the list. Select the launch IC and press the package button. 
Examine the Transcript for possible packaging problems. 

5. Copy the abt.ini file to yourname.ini, where yourname is the name that will 
also be used for the .icx file. Create the .icx file by executing the command: 
abt -i<lnch>.ic -hse<yourname>. i cx 

at the DOS prompt, where yourname is the name you wish to give to your 
.ICX file. See "Manually creating the ICX file" on page 346 for more 
information. 

6 . Invoke 

abt -i<yourname>. i cx -l<logfile.txt> 

to test your ICs. If the application does not start, examine walkback.log 
and logfile.txt for possible errors. 

Contrasting reduced run-time packaging and IC packaging 

The results of IC packaging are quite different from that of reduced run-time 
packaging. In reduced run-time packaging, the process proceeds as follows: 

1 . Determine the starting set of code to package by the leaf applications 
specified by the developer. The leaf applications are the ones that do not 
have any dependents. 

2. Using launch code provided by the developer in conjunction with the 
application hierarchy, use a pruning algorithm to determine the actual 
code that is used in the application. 

In contrast, IC packaging does not perform any algorithmic pruning. Any 
code present in an application that is destined to be packaged in an IC will be 
included in the IC. This means that potentially unused code in an application 
will still take up valuable memory if it is packaged. In particular, code that is 
only used at development time (like VisualAge Generator member extensions) 
should be moved into a separate application that will not be packaged to 
avoid it using up valuable memory at run time. 

Note: VAGen IC migration does not alter the prerequisites of your 

applications. You can continue to package your applications into a 
reduced run-time image after VAGen IC migration. 

Adding Variables, Object Factories, and View Wrappers 

VisualAge Generator IC packaging operates primarily on parts used on the 
Composition Editor canvas that hold onto class references to other views. The 
three most common mechanisms for view navigation are: 

1 . Use a View Wrapper to specify a view navigation. The view wrapper is 
then opened by invoking its open action. 

2. Create a new view instance using an Object Factory, and then open it. The 
Object Factory holds onto the class of the view to be instantiated. 
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3. Use an AbtVariable that is filled in with a view instance at run time. 

Connections are then made to the variable to manipulate it appropriately. 

VAGen Automated IC Packaging Migration examines these composition 
features and makes the appropriate part substitutions to allow for symbolic 
class references to be substituted for direct class references, and also to hook 
into the VAGen IC dynamic IC loading mechanism. The part substitutions are 
as described below: 

• AbtAppBldrViewWrapper->HptGuiClientPartWrapper 

• AbtVariable^HptGuiClientPartVariable 

• AbtObjectFactory->HptObjectFactory 

In addition, any direct class references in #abtBuildInternals associated with 
these classes are replaced by substituting the symbolic reference for the class. 

When creating new views to be added into your application for IC packaging, 
it is important that you use the correct (Hpt) VAGen parts if you want the 
view to work correctly in IC packaging as well as reduced run-time 
packaging. These parts are available in the VAGen Parts palette category and 
they are called VAGen IC Enabled Object Factory, View Wrapper and Variable 
respectively. 

To guarantee that the variable types have been added correctly, you can 
always run the IC migration utility prior to adding any definition containing a 
new application into the Component Manager. The migration utility will not 
create a new #abtBuildInternals method unless it has to be changed. 

Adding new views and applications into your executable 

After you have created new GUI views using the appropriate parts, as 
outlined in the section Adding Variables, Object Factories and View Wrappers, 
perform the following steps to incorporate your new view into the 
Component Manager for IC packaging: 

1 . Ensure that the prerequisites for the new applications are properly set up. 
Direct class references should only be to applications that are packaged 
into Prerequisite Components and not into Loadable Components. You 
should run Transcript-* Tools ->Query->Out of Scope References... as a 
precaution. 

2. Open the Component Manager View 

3. Press the Add button 

4. Define the new component. Specify the component name and file name. 
Ensure that the type is Loadable. Change the applications associated with 
the component to be the newly added application. 

5. Press the Make Executable button and follow the steps for normal IC 
packaging. 

The resulting new .exe and associated .icx file will dynamically load the new 
view when it is symbolically dereferenced. 
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Changing code 

Versioning or creating new editions of applications or classes in your image 
will cause the automated IC packager to repackage the components containing 
those applications, when you run Make Executable. It is highly recommended 
that all your applications are versioned prior to running the automated IC 
packager. 

Packaging errors 

Packaging warning and errors are output both to the Transcript and to the 
browser as shown in Figure 35. A browser will appear for each component 
that contains errors. Fatal errors will discontinue packaging of the component 
in which the error occurred. Informational messages (most of which pertain to 
use of particular snapshot files) are suppressed. 

Sample Transcript output for fatal error: 
Packaging Component IC GUI 2: 

ICGUI2»#someMethod - Reference to excluded class #ICGUI3 
A fatal error has occured. Packaging cannot continue 
Elapsed Time: 3:16 minutes 



^ Packager Control Panel for: IC Sample App2 IC 



Brum* Soil: Problem?;. 



HOD 



H:i i. ij'-rip eApp2| ICGUIj> jfenmeMethnd ■ Reference to e= eluded clj'v: »:C-UI3 



The class named $CGUI3 has been referenced in ICGUI2»#someMethod. 

The class named #iCGUI3 will be excluded from the image component, because the application the component is defined in has 
not been selected for packaging. 

Possible solutions are: 

(1) Add HptlCSampleApp3 to the list of applications to package (the root application the class named #ICGUI3 is defined in). 



|Show Errors and Fatal Ert 



j 

Find Problems Again 



Fatal errors are preventing output. 



Close 



Figure 35. Packaging problems 
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Snapshot (.snp) files 

Visual Age Generator uses .snp files to record information about packaged ICs, 
so that they can later be used as input into the packaging of other ICs that 
depend on them. The VAGen Automated IC packager will use .snp files to 
help determine which ICs need to be repackaged based on changes made to 
the code. If you delete .snp files, then the IC associated with it will have to be 
repackaged and if the IC is a prerequisite IC, then all loadable ICs dependent 
on it will also automatically be re-packaged. 

Manually creating the ICX file 

After packaging, the hptlnch.ic file can be used to launch your application. 
This will create the instance of HptComponentManager based on the input 
specified in the Component Manager view, and then launch the view specified 
in the launcher component. Creating an .icx file is a performance enhancing 
optimization. This step is normally performed for you automatically under the 
covers when you press the Make Executable button. However, on certain 
occasions you may have to perform this step manually. Creation of an icx file 
performs several important functions 

• Running the #loaded methods 

• Caching 

To create the .icx file, the following command from the DOS prompt: 
abt -ihptlnch.ic -hse<yourname>. i cx 

Technical details of ICs and class references 

Why are there two types of components, prerequisite and loadable, that 
VAGen developers have to specify during component definition? Their 
differences reflect the different kinds of class references that are used in a 
typical VAGen GUI application, as well as some technical constraints with ICs. 
VAGen GUI applications are typically composed of: 
Globally shared forms 

The forms that are used on many views. For example, the Personal 
Address form, the Employee summary form are examples of forms 
that might be reused on many views within the system. 
Subsystem specific shared forms 

The forms whose reuse is local to a specific subsystem. For example, 
the Account Reconciliation form might be used on views for many 
different account types. 
Views Views are not shared. View layouts are not shared, however they are 
related by navigation. In a typical VisualAge Generator GUI 
application, the number of views will far outnumber the number of 
shared forms. 

Any form (or any class reference - forms are just classes) that is shared 
between two or more applications must be packaged into a prerequisite 
component. Shared means that there exists direct class references to this form 
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from more than one application. The fact that the form must be packaged into 
a prerequisite component implies that applications containing shared forms 
must be packaged into prerequisite components. 

Applications containing views will typically be packaged into loadable 
components. Applications within Loadable components will only contain 
direct references to: 

• Non-shared classes that reside in the same application whose sole purpose 
is to support the view. 

• Shared classes in prerequisite components. 

In addition, applications within loadable components can contain symbolic 
references to: 

• Classes in other Loadable components 

The reason to distinguish the two types of references has to do with the order 
in which ICs are loaded into memory. If a direct reference to a class is made 
in a method, then when that method is loaded into memory, that class better 
already be present in memory or else the method will not resolve to the right 
reference and an error will occur when it executes. So, the IC containing the 
directly referenced class has to be loaded before the IC that contains the 
reference. This is the case with prerequisite ICs. Prerequisite ICs follow these 
rules. 

On the other hand, symbolic references are just that - Symbols. As long as 
there is mechanism to turn the symbolic reference into a class prior to sending 
it any messages, then there is no reason to load the IC that contains the 
symbolically referenced class prior to method execution. The IC that contains 
the class being referenced does not have to load until the method executes 
because there is no direct reference to be resolved when the method is loaded 
into memory. The IC that contains the class being referenced to be 
dynamically loaded, based on patterns of application execution - which is 
exactly the desired behavior for large VAGen GUI applications. Only load 
views when you need them, because the user has requested navigation to that 
particular view. 



Below is a table that describes the class reference types that are allowed for 
various combinations of IC types. 



From IC Type 


To IC Type 


Class Reference Type 


Allowed 


Prerequisite 


Prerequisite 


Direct 


Yes * 


Prerequisite 


Prerequisite 


Symbolic 


Yes 


Loadable 


Prerequisite 


Direct 


Yes * 


Loadable 


Prerequisite 


Symbolic 


Yes 
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From IC Type 


To IC Type 


Class Reference Type 


Allowed 


Loadable 


Loadable 


Direct 


No 


Loadable 


Loadable 


Symbolic 


Yes 


Prerequisite 


Loadable 


Direct 


No 


Prerequisite 


Loadable 


Symbolic 


No 



* Provided that the application that defines the class being referenced is a prerequisite 
application of the application containing the method where the reference is made. This 
also constrains the two applications to either be packaged in the same IC or two 
different prerequisite ICs that form a prerequisite /dependent relationship that match 
the applications' prerequisite /dependent relationship. 



Consider the applications in Figure 36 on page 349. Assume that each 
application is packaged into separate IC whose name is the same as the 
application. The letters correspond to class names that are defined within their 
containing application. The arrows as defined in the legend, underneath the 
figure. For prerequisite components (above the line in the figure), the structure 
of the IC prerequisites mirrors the structure of the application prerequisites. 
The same is true for prerequisite relationships from loadable components to 
prerequisite components. This means that before loading any loadable 
component, the prerequisite components must first be loaded into memory. 
For example, to load the view defined by Application 4, Application 2 must 
first be loaded. 

However, for loadable components, application prerequisite relationships that 
exist and drive reduce run-time packaging do not have an IC prerequisite 
counterpart. For example, there exists an application prerequisite relationship 
between Application 4 and Application 3, but no IC prerequisite relationship. 
So, Application 3 does not have to be loaded into memory before Application 
4. This is possible because the class references between Applications 3 and 4 
are symbolic - not direct, as shown in the diagram by the arrows between 
class E and class D. 

If you inadvertently specify a direct class reference from one Loadable 
component to another, it is caught and raised as a fatal error during the 
packaging process. A direct referenced class between two loadable 
components would be represented in the diagram by a pure dashed line 
between classes within two different applications below the line. Direct class 
references within the same application in a loadable component are allowed, 
as shown by the pure dashed line between C and D in Application 3. 
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Figure 36. Application relationships 

Pool dictionary references 

Pool Dictionary references are treated as direct class references. If a Pool 
Dictionary is referenced by more than one class, then the application that 
defines the Pool Dictionary must reside in a prerequisite component. 
References to the Pool Dictionary itself or to any of its entries are considered 
to be direct references. 

HptComponentManager class»#default Method 

The form of the generated #default method is as shown below: 
defaul t 

(HptComponentManager new 

addComponent : 

(HptPrerequisiteComponent new 
name: 'IC Sample Common Parts IC; 
icName: 'iccmn.ic'; 

addApplicationNamed: # 1 HptlCSampl eCommonPartsApp 1 withTimestamp: 3107273811; 
yoursel f) ; 

addComponent : 

(HptLoadabl eComponent new 
name: 'IC Sample Appl IC; 
icName: ' i csampl . i c ' ; 

addApplicationNamed: #' HptlCSampl eAppl ' withTimestamp: 3197273598; 

classNames: #( ' ICGUI 1 ' ' HptlCSampl eAppl ' ) 

yourself); 
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addComponent : 

(HptLoadabl eComponent new 
name: ' I C Sample App2 IC; 
icName: 'icsamp2.ic' ; 

addAppl icationNamed: # ' HptlCSampl eApp2 ' withTimestamp: 31G7273622; 
classNames: #( 1 ICGUI2 ' 1 HptlCSampl eApp2 1 ) 
yoursel f) ; 

11 other components " 

addComponent : 

(HptLaunchComponent new 
name: 'IC Sample Launcher 1 ; 
icName: 'icsamp.ic'; 
topLevelView: ' ICGUI1 ' ; 
yoursel f) ; 

yoursel f) 

VAGen IC packaging can be initiated from a Smalltalk script by sending the 
resulting HptComponentManager (the result of evaluating the above code) the 
message #package. 
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Part 4. Appendixes 
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Appendix A. DBCS name characteristics 

The following part naming conventions apply to all part types: 

• Part names cannot begin with the EZE prefix. 

• Part names cannot contain embedded blanks. 
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Appendix B. Command interface 



This section describes the VisualAge Generator command interface. The 
command interface is especially useful when you are processing requests that 
take a significant amount of time. The HPTCMD command implements the 
noninteractive command interface for VisualAge Generator. 

The subcommands can be used from a system prompt or from within another 
program. You can create a command file or program that issues several 
commands in sequence. The commands are not case sensitive, and you can 
type the options in any order. 

The following syntax diagram lists all the subcommands. 



-HPTCMD- 



-EXECUTE- 
-EXPORT- 
-IMPORT- 

-LIST 

-LISTA — 
-PRINT — 



Outputs of the commands 

Some of the subcommands produce a formatted report, a sequential file, or 
both. The formatted report is produced by default from the LIST and LISTA 
subcommands. 

The formatted report is directed to a standard output device (STDOUT). The 
standard output device is normally the screen, but can be other output 
devices, such as a printer, a NULL device, or a file. If output is directed to the 
screen, wrapping can occur. If you direct the output to the NULL device, the 
OUTFILE parameter is required for the LIST and LISTA subcommands. 

If you specify a file name for the OUTFILE parameter, the file produced can 
be used as the input file for the INFILE parameter on the other 
subcommands, such as EXPORT, LISTA, and PRINT: 

• The INFILE and OUTFILE parameters require unique file names when both 
parameters are specified together. 

• The OUTFILE parameter creates a sequential file in a specific format. See 
"Sequential file formats" on page 356 for more information. 
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• The INFILE parameter requires that the file specified be in the same specific 
format. Therefore, you can use the OUTFILE parameter to create a file to be 
used as input for the INFILE parameter. 

Each subcommand issues return codes giving feedback about the completion 
of the command. To have the return codes displayed on your screen, you 
must precede the subcommand with the EZERRC command. 

The return codes from subcommands differ from the VisualAge Generator 
Developer return codes. The following list shows a generic version of the 
subcommand return codes: 

0 The subcommand completed successfully. 

4 The subcommand completed, but with warnings. 

8 An error occurred while processing this subcommand. 

12 The syntax of this subcommand is not valid. 

Sequential file formats 

The following is the format for the sequential file for the input and output of 
the INFILE and OUTFILE parameters. 

Bytes Data description 

1-32 Part name. For maps, 1-6 for map group name and 8-15 for map 
name 

33 

34-37 Part type. The following are valid part types: 



ITEM 


Data items 


MAP 


Maps 


MAPG 


Map groups 


PRGM 


Programs 


PROC 


Processes 


PSB 


Program specification block 


RECD 


Records 


SGRP 


Statement groups 


TBLE 


Tables 


GOPT 


Generation options 


LTBL 


Linkage table 


RASC 


Resource associations 


BIND 


Bind control 


LEDT 


Link edit 


ALL 


All part types 


CTRL 


The control part types: GOPT, LTBL, RASC, BIND, 




and LEDT 



38 

39-N ENVY application or Java package name 
N+l 

N+2 - N+ll 

Date (MM/DD/YYYY) 
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N+12 

N+13 - N+20 

Time (HH:MM:SS) 

N+21 
N+22 

L if list was produced by LIST 

A if list was produced by LISTA 

Note: N is equal to the longest application or package name plus 39. 

Messages from the commands 

Each subcommand displays error messages. For message help or for return 
codes other than batch subcommand return codes, refer to the VisualAge 
Generator Messages and Problem Determination Guide document. 



EXECUTE subcommand (Smalltalk version) 

The /EXECUTE subcommand executes the given Smalltalk expression and 
displays the results. You can invoke Smalltalk methods that you have written 
and VAGen Smalltalk APIs provided with VisualAge Generator. For 
information on the VAGen Smalltalk APIs, see "Appendix D. Smalltalk APIs" 
on page 391. 

►* — HPTCMD — EXECUTE — Smal Italk expression ► 



The Smalltalk expression that is evaluated should return a collection of two 
values, an Integer and a String. The Integer value is the return code for the 
EXECUTE command. The String value is the result of the command which 
will be written to STDOUT. If nil is returned, nothing is written. If the 
Smalltalk expression does not return values for Integer and String, the return 
code will be zero and the returned object is displayed. 

HPTCMD The HPTCMD command provides the command interface 
functions for VisualAge Generator Developer. The first 
parameter you enter after HPTCMD is the subcommand. The 
HPTCMD command can be entered from a system prompt or 
from within another program or command file. 

Smalltalk expression 

Any valid Smalltalk expression. 

Return codes from the EXECUTE subcommand 

The return codes for the EXECUTE subcommand are as follows: 

n The first value returned as the result of evaluating the Smalltalk 

expression, n is an integer. 
8 The Smalltalk expression encountered an error. 
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Execute subcommand examples 

hptcmd execute Transcript cr; show: 'Hello world! 1 
hptcmd execute ABCBui 1 dControl prepareForBuild: 1 97 1022 



EXECUTE subcommand (Java version) 

The EXECUTE subcommand invokes the given Java method and returns the 
results. You can invoke Java methods you have written which use the VAGen 
Java APIs provided with VisualAge Generator. For information on the VAGen 
Java APIs, see "Appendix C. Java APIs" on page 375. 



**■ — HPTCMD — EXECUTE — package. Class .method — (- 



-argumen t- 



The method invoked must be a public static (class) method, and the class 
cannot exist in a default package. You may specify zero or more arguments. 
Arguments are literals and can be of type long integer, boolean, and String. 
String literals are enclosed in single quotation marks (') instead of double 
quotation marks (") as is the usual Java syntax. 

The method must return a Vector containing two elements, an Integer and a 
String. The value of the Integer is the return code for the EXECUTE 
command. The String value will be written to STDOUT. If something other 
than a Vector containing an Integer and String is returned, the return code 
will be one. 

Return codes from the EXECUTE subcommand 

8 An error occurred parsing the command or executing the method. 

Execute subcommand examples 

hptcmd execute myPackage.MyClass.outputReport() 

hptcmd execute myPackage.MyClass.performBuild( 1 2000-01-01 ' , true ) 

hptcmd execute myPackage.MyClass.ven'fyUser( 'John Doe', 12345 ) 



EXPORT subcommand 

The EXPORT subcommand exports parts to an external source format file. 

HPTCMD— EXPORT— /ESF=/iZe name — , 1 ► 

I— /NAME=parf name-* 
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7type= 



r 



ITEM- 
MAP— 
■MAPG- 
PRGM- 
PROC- 
■PSB- 
-RECD- 
■SGRP- 
■TBLE- 
GOPT- 
LTBL- 
RASC- 
BIND- 
■LEDT- 
ALL- 
CTRL- 



r 



-/APP=— - — ENVY application name- 



r 



-/PKG= — - — package name- 



L/INFILE; 



XT 



J 



■file name 



/REPLACE 



HPTCMD The HPTCMD command provides the command interface 
functions for VisualAge Generator Developer. The first 
parameter you enter after HPTCMD is the subcommand. The 
HPTCMD command can be entered from a system prompt or 
from within another program or command file. 

EXPORT The EXPORT subcommand exports to an external source 

format file the parts matching the criteria specified in the 
/ name, / type, / app, and / pkg options. If you do not specifiy 
any criteria, all parts in the image are exported. 

Note: When running multiple EXPORTs in batch, VisualAge 
Generator Developer closes the serial file after each 
command is run. 

/ESF The /ESF parameter specifies the file destination of the 

output. If there are any spaces in what you specify for this 
parameter, you must enclose this entire parameter in double 
quotation marks (" "). 

/NAME The name parameter specifies the name of the parts you want 

exported. 

The part name can contain the following wildcards: * or # 
/TYPE The type parameter specifies the VAGen type of the parts you 
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want exported. You can specify multiple combinations of part 
types using plus and minus. The following are the valid part 



types: 




ITEM 


Data items 


MAP 


Maps 


MAPG 


Map Groups 


PRGM 


Programs 


FUNC 


Functions 


PSB 


Program specification block 


RECD 


Records 


TBLE 


Tables 


GOPT 


Generation options 


LTBL 


Linkage table 


RASC 


Resource associations 


BIND 


Bind control 


LEDT 


Link edit 


ALL 


All part types 


CTRL 


Control part types (GOPT, LTBL, RASC, 




BIND, and LEDT) 



You can specify part types in any order. You can use the 3 or 
4 letter keyword, or you can abbreviate to any length. All 
types matching the abbreviation are included. For instance, M 
indicates both maps and map groups and PR indicates 
Programs and Processes. All matching types are included. 

You can specify part types in any order. 

Use a plus sign (+) to separate part types to include in the 
export. Do not put spaces between the part types and the plus 
sign (+). 

Use a minus sign (-) to specify part types that should not be 
included in the list. Do not put spaces between the part types 
and the minus sign (-). 

You can use an ALL followed by a minus sign (-) to list all 
part types except types listed after the minus signs. 

The following example specifies that you want all part types 
except records and PSBs. The P stands for PSBs and Processes. 
You must specify the +PRGM so that Programs are included. 
/TYPE=ALL-R-P+PRGM 

The following example specifies that you want all Programs, 
PSBs, Functions, Maps, Map groups, Tables, and Records: 
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/TYPE=ALL- ITEM-CTRL 



/APP The APP parameter, used only in the Smalltalk version of 

VisualAge Generator, specifies the names of the ENVY 
applications you want exported. 

Names can contain the following wildcards: * or #. The 
following example includes all applications that begin with 
HptSample: /APP=HptSampl e* 

You can specify multiple application names separated with 
commas. 

/PKG The PKG parameter, used only in the Java version of 

VisualAge Generator, specifies the names of the Java packages 
you want exported. 

Names can contain the following wildcards: * or #. The 
following example includes all packages that begin with 
HptSample: /PKG=HptSampl e* 

You can specify multiple package names separated with 
commas. 

/INFILE The /INFILE parameter specifies a sequential file containing 

the parts you want to export. The file name specified must be 
a valid file name. 

You can use the LIST and LISTA subcommands to create a 
sequential file that can be used on the INFILE parameter. 

If the INFILE parameter is specified, /NAME, /TYPE, and 
/APP or /PKG are ignored. 

The export occurs only when the part name, part type, and 
application or package specified in the sequential file match 
the ones found in the image. 

Only the part name, part type, and application or package are 
used from the sequential file. 

/REPLACE The /REPLACE parameter specifies that you want to replace 
an existing external source format file. 

If you specify this parameter and the file that you are 
exporting to already exists, the existing file is overwritten with 
the new external source format data. 

If you do not specify this parameter and the file that you are 
exporting to already exists, the external source format data is 
appended to the end of the file. 
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You can use the LIST and LISTA subcommands to create a sequential file to 
use with the INFILE parameter. See "Sequential file formats" on page 356 for 
more information. 

Return codes from the EXPORT subcommand 

The return codes for the EXPORT subcommand are as follows: 



0 



8 

12 



The part, list of parts, application, or package was exported 
successfully. 

The part, list of parts, application, or package was exported 
successfully, but some messages were issued. 
The part, list of parts, application, or package was not exported. 
The command syntax is not valid. 



EXPORT Subcommand examples 

hptcmd export /app=HptSampl eEzerempParts /esf=h:\work\ezeremp.esf 
hptcmd export /pkg=HptSampl eEzerempParts /esf=h:\work\ezeremp.esf 



IMPORT subcommand 



The IMPORT subcommand imports parts from an external source format file 
into the specified target ENVY application or Java package. 



►♦—HPTCMD— IMPORT- 



-/ESF=/iZe name — /TARGETAPP= — ENVY application name- 
L/TARGETPKG= — Java package name 



J 



/DUPAPP= 
/DUPPKG= 



-defined 

-target 

-targetonly- 



L 



/NOBYPASS 



r 



/USER=unique name- 



/PASSWRD=password name 



HPTCMD 



IMPORT 



The HPTCMD command provides the command interface 
functions for VisualAge Generator Developer. The first 
parameter you enter after HPTCMD is the subcommand. The 
HPTCMD command can be entered from a system prompt or 
from within another program or command file. 



The IMPORT subcommand imports parts from an external 
source format file into the specified target ENVY application 
or Java package. 
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/ESF The /ESF parameter specifies the source of the input. If there 

are any spaces in what you specify for this parameter, you 
must enclose this entire parameter in double quotation marks 
(" ")■ 

/DUPAPP The /DUPAPP parameter, valid only in the Smalltalk version 
of VisualAge Generator, determines which application a part 
will be stored in if the part you are importing already exists in 
the image. 

none Does not import duplicate parts. This is the 

default if the /DUPAPP option is not 
specified. 

defined Imports the selected parts. If the part exists in 

any application in your image, it will be 
replaced in that application. 

target Imports the selected parts to the target 

application. If the part exists in any 
application in your image, except the target 
application, it will be deleted from the 
containing application and placed in the target 
application. 

targetonly Imports the selected parts to the target 
application. If the part exists in any 
application in your image, except the target 
application, it will not be imported. 

/DUPPKG The /DUPPKG parameter, valid only in the Java version of 
VisualAge Generator, is the same as /DUPAPP except that it 
applies to packages instead of applications. 

/NOBYPASS The /NOBYPASS parameter specifies not to import parts if 

the import operation detects an error during validation of the 
parts in the external source format file. The import operation 
validates the entire external source format file, and, if errors 
occur when NOBYPASS is specified, parts are not imported to 
the target application. 

If NOBYPASS is not specified and validation errors are found, 
any valid parts are imported. 

/USER The /USER parameter determines which user will be the 

developer of the imported parts after the parts are in the 
library. If a part class is created, the specified user will be the 
owner. The user name must be the Unique name defined in 
ENVY, not the Network name. 

/PASSWORD The /password parameter is required if VisualAge Generator 
has been configured to require passwords. 
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Return codes from the IMPORT subcommand 

The return codes for the IMPORT subcommand are as follows: 

0 The part, list of parts or application was imported successfully. 

4 The part, list of parts or application was imported successfully, but 

some messages were issued. 
8 The part, list of parts or application was not imported. 

12 The command syntax is not valid. 

IMPORT Subcommand examples 

hptcmd import esf=h:\work\ezeremp.esf /targetapp=HptSampl eEzerempParts /dupapp=defined 



LIST subcommand 



The LIST subcommand creates a list of parts that match the /NAME, /TYPE, 
and /APP or /PKG criteria. The list can be used for information or for input 
to other subcommands. 



-HPTCMD— LIST- 



r 



/NAME=parf name 



T 



-+ or 



7TYPE=— 



ITEM- 
-MAP— 
— MAPG- 
■PRGM- 
PROC- 
PSB- 
RECD- 
SGRP- 
■TBLE- 
GOPT- 
LTBL- 
RASC- 
■BIND- 
— LEDT- 
■ALL- 
CTRL- 



/APP=— ENVY application name 



7S0RTBY= 



-type 

-app 

-edition- 



-/PKG= — package name- 



7S0RTBY= 



type 

-pkg 

-edition- 
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■/OUTFILE=/£Ze name 



HPTCMD The HPTCMD command provides the command interface 
functions for VisualAge Generator Developer. The first 
parameter you enter after HPTCMD is the subcommand. The 
HPTCMD command can be entered from a system prompt or 
from within another program or command file. 

LIST The LIST subcommand creates a list of parts that matches the 

search criteria specified. 

/NAME The name parameter specifies the name of the parts you want 

to list. 

The part name can contain the following wildcards: * or # 

/TYPE The type parameter specifies the VAGen type of the parts you 

want to list. You can specify multiple combinations of part 
types using plus and minus. The following are the valid part 



types: 




ITEM 


Data items 


MAP 


Maps 


MAPG 


Map Groups 


PRGM 


Programs 


FUNC 


Functions 


PSB 


Program specification block 


RECD 


Records 


TBLE 


Tables 


GOPT 


Generation options 


LTBL 


Linkage table 


RASC 


Resource associations 


BIND 


Bind control 


LEDT 


Link edit 


ALL 


All part types 


CTRL 


Control part types (GOPT, LTBL, RASC, 




BIND, and LEDT) 



You can specify part types in any order. You can use the 3 or 
4 letter keyword, or you can abbreviate to any length. All 
types matching the abbreviation are included. For instance, M 
indicates both maps and map groups and PR indicates 
Programs and Processes. All matching types are included. 

You can specify part types in any order. 
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Use a plus sign (+) to separate part types to include in the 
export. Do not put spaces between the part types and the plus 
sign (+). 

Use a minus sign (-) to specify part types that should not be 
included in the list. Do not put spaces between the part types 
and the minus sign (-). 

You can use an ALL followed by a minus sign (-) to list all 
part types except types listed after the minus signs. 

The following example specifies that you want all part types 
except records and PSBs. The P stands for PSBs and Processes. 
You must specify the +PRGM so that Programs are included. 
/TYPE=ALL-R-P+PRGM 

The following example specifies that you want all Programs, 
PSBs, Functions, Maps, Map groups, Tables, and Records: 
/TYPE=ALL- ITEM-CTRL 

/APP The /APP parameter specifies the names of the ENVY 

applications you want exported. 

Names can contain the following wildcards: * or #. The 
following example includes all applications that begin with 
HptSample: /APP=HptSampl e* 

You can specify multiple application names separated with 
commas. 

/PKG The /PKG parameter specifies the names of the Java packages 

you want exported. 

Names can contain the following wildcards: * or #. The 
following example includes all packages that begin with 
HptSample: /PKG=HptSampl e* 

You can specify multiple package names separated with 
commas. 

/OUTFILE The /OUTFILE parameter specifies the name of the sequential 
file you want to use as the OUTFILE. You can use the 
OUTFILE as input for other subcommands. 

The name must be a valid file name. 

See "Sequential file formats" on page 356 for a description of 
the format. 

If the file specified with the / OUTFILE parameter is a file that 
already exists, the list is appended to the end of the file. If 
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you want the list to start a new file but have the same file 
name, you must delete the file between subcommands. 

/SORTBY The /SORTBY parameter specifies how output will be sorted. 

This parameter applies to the formatted report as well as the 
data written to the OUTFILE. By default, output is sorted by 
NAME. 

Return codes from the LIST subcommand 

The return codes for the LIST subcommand are as follows: 
0 The list was built successfully. 

4 No parts were found, so the list was not built. 

12 The command syntax is not valid. 

LIST Subcommand example 

hptcmd list /type=prgm /app=HptSampl eEzerempParts /sortby=edition 
hptcmd list /type=prgm /pkg=HptSampl eEzerempParts /sortby=edition 

hptcmd list /name=e* /type=al 1 -Ctrl /outfile=h:\work\l ist.out 

hptcmd list /type=recd+tbl e /app=HptSampleEzerempParts,HptSampleStaffParts 
hptcmd list /type=recd+tbl e /pkg=HptSampleEzerempParts,HptSampleStaffParts 



LISTA subcommand 



The LISTA subcommand creates a list of associated parts for the parts 
matching the /NAME, /TYPE, and /APP or /PKG criteria. If no criterion is 
specified, associates for all parts in the image are listed. You can use the list 
for information or for input to other subcommands. 



-HPTCMD— LISTA- 



r 



/NAME=port name- 



7TYPE=— 



ITEM- 
MAP— 
■MAPG- 
PRGM- 
PROC- 
PSB— 
■RECD- 
-SGRP- 
■TBLE- 
GOPT- 
LTBL- 
RASC- 
BIND- 
LEDT- 
■ALL- 
CTRL- 
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r 



-/APP= — - — ENVY application name- 



/PKG= — - — package name- 



r 



/INFILE=/zZe name 



J 



T 



r 



/OUTFILE=/iZe name 



HPTCMD The HPTCMD command provides the command interface 
functions for VisualAge Generator Developer. The first 
parameter you enter after HPTCMD is the subcommand. The 
HPTCMD command can be entered from a system prompt or 
from within another program or command file. 

LISTA The LISTA subcommand creates a list of associated parts for 

information or for input to other subcommands. 

/NAME The name parameter specifies the name of the parts you want 

to list associates for. 

The part name can contain the following wildcards: * or # 

/TYPE The type parameter specifies the VAGen type of the parts you 

want to list associates for. You can specify multiple 
combinations of part types using plus and minus. The 
following are the valid part types: 
ITEM Data items 

MAP Maps 
MAPG Map Groups 

PRGM Programs 
FUNC Functions 
PSB Program specification block 

RECD Records 
TBLE Tables 
GOPT Generation options 

LTBL Linkage table 

RASC Resource associations 

BIND Bind control 

LEDT Link edit 

ALL All part types 

CTRL Control part types (GOPT, LTBL, RASC, 

BIND, and LEDT) 
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You can specify part types in any order. You can use the 3 or 
4 letter keyword, or you can abbreviate to any length. All 
types matching the abbreviation are included. For instance, M 
indicates both maps and map groups and PR indicates 
Programs and Processes. All matching types are included. 

You can specify part types in any order. 

Use a plus sign (+) to separate part types to include in the 
export. Do not put spaces between the part types and the plus 
sign (+). 

Use a minus sign (-) to specify part types that should not be 
included in the list. Do not put spaces between the part types 
and the minus sign (-). 

You can use an ALL followed by a minus sign (-) to list all 
part types except types listed after the minus signs. 

The following example specifies that you want all part types 
except records and PSBs. The P stands for PSBs and Processes. 
You must specify the +PRGM so that Programs are included. 
/TYPE=ALL-R-P+PRGM 

The following example specifies that you want all Programs, 
PSBs, Functions, Maps, Map groups, Tables, and Records: 
/TYPE=ALL- ITEM-CTRL 

/APP The / APP parameter specifies the names of the ENVY 

applications you want exported 

Names can contain the following wildcards: * or #. The 
following example includes all applications that begin with 
HptSample: /APP=HptSampl e* 

You can specify multiple application names separated with 
commas. 

/PKG The /PKG parameter specifies the names of the Java packages 

you want exported. 

Names can contain the following wildcards: * or #. The 
following example includes all packages that begin with 
HptSample: /PKG=HptSampl e* 

You can specify multiple package names separated with 
commas. 

INFILE The INFILE parameter specifies a sequential file containing 
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the parts you want to list associates for. The file name 
specified must be a valid file name. 

You can use the LIST and LISTA subcommands to create a 
sequential file that can be used on the INFILE parameter. 

If the INFILE option is specified, /NAME, /TYPE, and /APP 
or /PKG are ignored. 

The list of associates is created only when the part name, part 
type, and application or package specified in the sequential 
file match the ones found in the image. 

Only the part name, part type, and application are used from 
the sequential file. 

/OUTFILE The /OUTFILE parameter specifies the name of the sequential 
file you want to use as the OUTFILE. You can use the 
OUTFILE as input for other subcommands. 

The name must be a valid file name. 

See "Sequential file formats" on page 356 for a description of 
the format. 

If the file specified with the /OUTFILE parameter is a file that 
already exists, the list is appended to the end of the file. If 
you want the list to start a new file but have the same file 
name, you must delete the file between subcommands. 

Return codes from the LISTA subcommand 

You can use the LISTA subcommand to create a sequential file that can be 
used on the INFILE parameter. See "Sequential file formats" on page 356 for 
more information. 

The return codes for the LISTA subcommand are as follows: 
0 The list of associates was built successfully. 

4 The list of associates was built successfully, but some messages were 

issued. 

12 The command syntax is not valid. 
LISTA Subcommand example 

hptcmd lista /name=pgml 

hptcmd lista /infile=h:\work\list.out /outfile=lista.out 

PRINT subcommand 

The PRINT subcommand prints part definitions. 
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-HPTCMD — PRINT- 



r 



/NAME=port name 



T 



r 



7TYPE=— pITEM- 

-MAP— 
-MAPG- 
-PRGM- 
-PROC- 
-PSB— 
— RECD- 
■SGRP- 
TB LE- 
GO PT- 
LTBL- 
RASC- 
BIND- 
■LEDT- 
ALL- 
CTRL- 



L/INFILE : 



J 



r 



-/APP=— - — ENVY application name- 



/PKG= — - — package name- 



file name 



r 



/DEVICE=dei/ice name- 



HPTCMD The HPTCMD command provides the command interface 
functions for VisualAge Generator Developer. The first 
parameter you enter after HPTCMD is the subcommand. The 
HPTCMD command can be entered from a system prompt or 
from within another program or command file. 

PRINT The PRINT subcommand prints part definitions. 

/NAME The name parameter specifies the name of the parts you want 

to list associates for. 

The part name can contain the following wildcards: * or # 

/TYPE The type parameter specifies the VAGen type of the parts you 

want to list associates for. You can specify multiple 
combinations of part types using plus and minus. The 
following are the valid part types: 
ITEM Data items 

MAP Maps 
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MAPG 


Map Groups 


PRGM 


Programs 


FUNC 


Functions 


PSB 


Program specification block 


RECD 


Records 


TBLE 


Tables 


GOPT 


Generation options 


LTBL 


Linkage table 


RASC 


Resource associations 


BIND 


Bind control 


LEDT 


Link edit 


ALL 


All part types 


CTRL 


Control part types (GOPT, LTBL, RASC, 




BIND, and LEDT) 



You can specify part types in any order. You can use the 3 or 
4 letter keyword, or you can abbreviate to any length. All 
types matching the abbreviation are included. For instance, M 
indicates both maps and map groups and PR indicates 
Programs and Processes. All matching types are included. 

You can specify part types in any order. 

Use a plus sign (+) to separate part types to include in the 
export. Do not put spaces between the part types and the plus 
sign (+). 

Use a minus sign (-) to specify part types that should not be 
included in the list. Do not put spaces between the part types 
and the minus sign (-). 

You can use an ALL followed by a minus sign (-) to list all 
part types except types listed after the minus signs. 

The following example specifies that you want all part types 
except records and PSBs. The P stands for PSBs and Processes. 
You must specify the +PRGM so that Programs are included. 

/TYPE=ALL-R-P+PRGM 

The following example specifies that you want all Programs, 
PSBs, Functions, Maps, Map groups, Tables, and Records: 
/TYPE=ALL- ITEM-CTRL 

/APP The /APP parameter specifies the names of the ENVY 

applications you want exported. 
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Names can contain the following wildcards: * or #. The 
following example includes all applications that begin with 
HptSample: /APP=HptSampl e* 

You can specify multiple application names separated with 
commas. 

/PKG The /PKG parameter specifies the names of the Java packages 

you want exported. 

Names can contain the following wildcards: * or #. The 
following example includes all packages that begin with 
HptSample: /PKG=HptSampl e* 

You can specify multiple package names separated with 
commas. 

/INFILE The INFILE parameter specifies a sequential file containing 

the parts you want to list associates for. The file name 
specified must be a valid file name. 

You can use the LIST and LISTA subcommands to create a 
sequential file that can be used on the INFILE parameter. 

If the INFILE option is specified, /NAME, /TYPE, and /APP 
or /PKG are ignored. 

The print occurs only when the part name, part type, and 
application or package specified in the sequential file match 
the ones found in the image. 

Only the part name, part type, and application or package are 
used from the sequential file. 

/DEVICE The /DEVICE parameter specifies the destination printer 

device for the printer listings. 

If this parameter is not specified, the printer selected in the 
Print Setup window will be used. If no printer has been 
selected, the default printer will be used. 

Return codes from the PRINT subcommand 

The return codes for the PRINT subcommand are as follows: 

0 The part or list of parts was printed successfully. 

4 The part or list of parts was printed successfully, but some messages 

were issued. 
8 The part or list of parts was not printed. 

12 The command syntax is not valid. 

PRINT Subcommand example 

hptcmd print /app=HptSampl eEzerempParts /device=\\carprll\carpsl5 
hptcmd print /pkg=HptSampl eEzerempParts /device=\\carprll\carpsl5 
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hptcmd print /name=Mdl* /type=prgm 
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Appendix C. Java APIs 



The VAGen Java APIs described in this section enable you to perform 
additional name validation on VAGen parts, perform user administration, add 
menu items to the VAGen Parts Browser, and provide an interface to VAGen 
part utilities. 

The APIs are not added to the Workspace as part of the IBM VisualAge 
Generator feature. To add the APIs, from the VisualAge for Java QuickStart 
add the IBM VisualAge Generator Utilities feature. Adding the feature will 
add the IBM VisualAge Generator Utilities project and the IBM IDE Utility 
class libraries project to your Workspace. The IBM VisualAge Generator 
Utilities project contains the com.ibm.vgj.devutil package which contains all 
the VAGen classes described in this section. 

The IBM IDE Utility class libraries project contains the VisualAge for Java Tool 
Integration classes. These classes can be used to query and work with 
Workspace and Repository objects, such as Projects, Packages, Classes and 
Interfaces. Before using the VisualAge for Java classes, you must add the 
"project_resources\IBM IDE Utility local implementation" directory to your 
class path. See the VisualAge for Java product help for information on how to 
use the utility classes. 

Most of the APIs are defined in the VAGenUtilitylnterface class. VAGen part 
types used in the APIs are defined in the VAGenConstants class. See 
"Supporting classes" on page 384 for more information on VAGenConstants 
and other supporting classes. 



Part name validation 

You can customize part name validation beyond the standard VAGen 
validation by creating a subclass of VAGenPartNameValidationHandler and 
registering it using the addPartNameValidationHandler method of the 
VAGenUtilitylnterface class. Multiple handlers can be registered, and they will 
be called in the order they were registered. VAGen validates part names when 
new parts are created and when parts are added within another part, such as 
a working storage record in a program. 

VAGenPartNameValidationHandler is an abstract class with one public method: 



public abstract boolean val i date (String name, long type, Package pkg) 
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The method returns true if the part name passes validation. Returning false 
will prevent the part from being created. The part's package is not always 
known when the part name is validated, so the pkg argument may be null 
when the validate method is called. For example, when a main function is 
added to a program the function name is validated, however, the package for 
the function has not yet been specified, so the pkg argument will be null 
when the validate method is called. 

Part names are not validated during VAGen Import. You can create parts 
during import that do not meet the criteria of your validation handlers. 

The following shows an example validation handler subclass. The validate 
method ensures that all VAGen Records end with "RCD", and that all VAGen 
parts begin with the first three letters of the package that contains them. 



package myPackage; 

import com. ibm. i vj . uti 1 .base. Package; 
import com. ibm. vgj .devuti 1 .*; 

class MyHandler extends VAGenPartNameVal idationHandler { 

public boolean validate(String name, long type, Package pkg) { 

if( (type & VAGenConstants . PART_TYPE_RECORD) == 
VAGenConstants . PART_TYPE RECORD ) { 
if( name.lengthO <= 6 | 

!name.substring(name.length()-3, name.lengthO) .equal s ("RCD") ) 
return false; 

} 

if( pkg != null && 

!pkg.getName() .substring(G,3) .equalsIgnoreCase(name.substring(G,3)) ) 
return false; 

return true; 

} 

} 

Once your handler class has been defined, use the following 
VAGenlltilitylnterface class methods to add and remove handlers. 

public static boolean addPartNameVal idationHandler(String handlerClassName) 
public static boolean removePartNameVal idationHandler (String 

handlerClassName) 
public static void removeAHPartNameValidationHandlers() 

handlerClassName is the name of a subclass of VAGenPartNameValidationHandler, 
and it must be qualified with its package name. Adding a handler class will 
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cause an instance of it to be created, using a constructor which takes no 
arguments. Once a handler has been registered, an instance of it will be 
created each time VisualAge for Java is started. 

The addPartNameValidationHandler and removePartNameValidationHandler 
methods return a boolean indicating whether the operation succeeded. The 
add will fail if the class is not a subclass of VAGenPartNameValidationHandler, 
if the class name has not been qualified with the package name, or if an 
instance of the class cannot be created. The remove will fail if the given class 
name was not previously added. 



User administration 

The following VAGenUtilitylnterface methods provide APIs to perform user 
administration. VisualAge for Java provides APIs to get and set the current 
Workspace Owner. See Workspace.getCurrentOwnerNameO and changeOwnerO in 
the VisualAge for Java Help System. 

public static boolean addGroupMember (Package pkg, String uniqueName) 

Add the specified user to the package user group. Return true if the user was 
added successfully. Only the Administrator or Package owner may add users 
to the group. 



public static boolean addUser (String uniqueName, String fullName, String 
networkName) 

Add a new user. Return true if the user was created successfully. Only the 
Administrator may create new users. 



public static String getUserFul 1 Name (String uniqueName) 

Return the full name of the specified user, or null if the user does not exist. 



public static String getUserNetworkName (String uniqueName) 

Return the network name of the specified user, or null if the user does not 
exist. 



public static String[] getVal idUsers() 
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Return an array of the unique names of the currently defined users. 



public static boolean removeGroupMember (Package pkg, String 
uniqueName) 

Remove the specified user from the package user group. Return true if the 
user was removed successfully. Only the Administrator or Package owner 
may add users to the group. 



public static boolean removellser (String uniqueName) 

Remove the specified user. Return true if the user was deleted successfully. 
Only the Administrator can delete users. 



public static boolean setOwner (Model model, String uniqueName) 

Set the owner of the specified Workspace or Repository object. Model may be 
a Project, ProjectEdition, Package, PackageEdition, Type, or TypeEdition. 
Return true if the owner was set successfully. Only the Administrator or the 
current owner of the object can set the owner. 



public static boolean updatellser (String uniqueName, String newFullName, 
String newNetworkName) 

Update the full name and network name of the specified user. Return true if 
the information was updated successfully. Only the Administrator can update 
user information. 



Parts Browser menu customization 

The following VAGenUtilitylnterface methods provide the means to add menu 
items and separators to the VAGen Parts Browser. 



public static boolean addPartsMenuItem(String itemName, String 

1 i stenerCl assName, int enabled) 
public static void addPartsMenuSeparator(String separatorName) 
public static boolean removePartsMenuItem(String itemName) 

public static boolean addTool sMenuItem(String itemName, String 

1 i stenerCl assName) 
public static void addTool sMenuSeparator (String separatorName) 
public static boolean removeTool sMenuItem (String itemName) 
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The first three methods are used to add to and remove from the VAGen Parts 
menu. The last three methods are used to add to and remove from the Tools 
menu. Items added to the VAGen Parts menu will appear on a Tools cascade 
menu. Items and separators appear in the order they were added. 

itemName is the name of the menu item. A tilde character ( ) can be placed 
before one of the characters in itemName to indicate the menu mnemonic. 
The tilde character should not be specified when removing the menu item. 
separatorName is used to identify the separator so that it may be removed. 

listenerClassName is the name of a class which implements the 
VAGenActionListener interface. See the Supporting Classes section for more 
information on the VAGenActionListener interface. The class name must be 
qualified with its package name. Adding a menu item will cause an instance 
of the listener class to be created, using a constructor which takes no 
arguments. Once a menu item has been added, an instance of the listener 
class will be created each time VAJava is started. 

The enabled parameter of the addPartsMenuItem method is a constant which 
determines when the menu item will be enabled based on how many VAGen 
Parts are selected in the browser. See the MENU_ENABLED constants in the 
VAGenConstants class for valid values. 

addPartsMenuItem and addToolsMenuItem will return true if the item was 
added successfully, false will be returned if the listenerClassName is not 
qualified with its package name, if the listener class does not implement the 
VAGenActionListener interface, or if an instance of the listener class cannot be 
created. removePartsMenuItem and removeToolsMenuItem will return true if 
the menu was removed succesfully and false if the item was not found. 

When the menu item is selected in the VAGen Parts Browser, the 
actionPerformed method in the listener class will be called and passed a 
VAGenActionEvent instance containing information about the menu event. 
getActionCommand() will return the name of the menu item that was 
selected. For items on the VAGen Parts menu, getActionData() will return a 
Vector of VAGenPartlnformation instances representing the VAGen parts 
currently selected in the VAGen Parts Browser. For items on the Tools menu, 
getActionData() will return null. 

The following example implements a menu action listener which will open a 
VAGen part editor on the part which was selected in the browser, 
package listener; 

import com. i bm. vgj .devuti 1 .*; 
import java.uti 1 .Vector; 

public class Exampl eLi stener implements VAGenActionListener { 
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public void actionPerformed(VAGenActionEvent e) { 



Vector v = (Vector) e.getActionData() ; 

VAGenPartlnformation pi = (VAGenPartlnformation) v.firstElement() ; 
VAGenUti 1 i tylnterface.edi tPart (pi .getName() , pi .getType() ) ; 

} 

} 

Once the class is defined, the menu item can be added to the VAGen Parts 
menu of the browser by executing the following: 

VAGenUti 1 ityInterface.addPartsMenuItem( 
"My Open", 

"1 i stener. Exampl eLi stener" , 
VAGenConstants .MENU_ENABLED_ONE_SELECTED ) 



VAGen Utilities 

The VAGenlltilitylnterface class provides API access to VAGen part utilities. See 
"Supporting classes" on page 384 for information on classes used in 
conjunction with the VAGenlltilitylnterface methods. 

A number of the following methods take parameters which specify a set of 
VAGen parts. These parameters are a part name pattern, a part type, and a 
Vector of Package or PackageEdition instances. The part Infos method is an 
example: 



public static Vector partlnfos (String name, long type, Vector packages) 

The name parameter is a String which may contain wildcard characters. An 
asterisk (*) matches zero or more characters, and a pound sign (#) matches 
exactly one character. 

The type parameter is a long integer. Valid values are found in the part type 
static fields defined in the VAGenConstants class. This parameter may also be a 
bitwise-or'ing of several part types. 

The packages parameter is a Vector of Package or PackageEdition instances, 
specifying the location of the part. A Package instance represents a Java 
package currently loaded in the Workspace. A PackageEdition instance 
represents a package in the repository which may or may not be currently 
loaded in the Workspace. Both classes are defined in the com.ibm.ivj .util.base 
package. See the VisualAge for Java help for more information on the 
Visual Age for Java Tool Integration classes. 
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The packages parameter may be null, in which case all packages loaded in the 
Workspace will be used. 

The partlnfos method returns a collection of VAGenPartlnformation instances 
matching the parameter specifications. The following example will return 
Program and Function parts whose name begins with "E", and which exist in 
the edition of the samplel package loaded in the Workspace, or in the most 
recent edition of the sample2 package which does not need to be loaded in 
the Workspace. 

import java.uti 1 .Vector; 

import com. i bm. i vj .util .base. Tool Env; 

import com.ibm.ivj .util .base. Workspace; 

import com. i bm. i vj .uti 1 .base. Repository; 

import com.ibm.ivj .util .base. Package; 

import com.ibm.ivj .util . base. PackageEdit ion; 

import com. i bm. vgj .devuti 1 .VAGenConstants; 

import com. i bm. vgj .devuti 1 .VAGenUti 1 ity Interface; 

Workspace ws = Tool Env. connectToWorkspace() ; 
Repository rep = ws .getReposi tory () ; 
Package pi = ws . 1 oadedPackageNamed ("sampl el") ; 
PackageEdition p2 = rep.getPackageEditions("sample2") [G] ; 
Vector packages = new Vector(2); 
packages. addEl ement (pi) ; 
packages. addEl ement (p2) ; 
Vector parts = 
VAGenUti 1 i ty Interface. partlnfos ( 
"E*" , 

VAGenConstants . PART_TYPE_PROGRAM | VAGenConstants . PART_TYPE_FUNCTION , 
packages ) ; 

Upon execution of this code, the parts Vector will contain 
VAGenPartlnformation instances. This Vector can be passed to other 
VAGenlltilitylnterface methods which take a set of parts as input. 

The following part utility methods are defined in the VAGenlltilitylnterface 
class. 



public static Vector associatesOfParts(String name, long type, Vector 
packages) 

public static Vector associatesOf Parts (Vector parts) 
public static Vector idAssociatesOf Parts (String name, long type, Vector 
packages) 

public static Vector idAssociatesOf Parts (Vector parts) 

Return a Vector a parts which are associates of the part(s) specified by the 
parameters. The first and third methods take a part name pattern, a part type 
mask, and a Vector of Package or PackageEditions to specify the parts to search 
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for associates. The second and fourth methods take a Vector of 
VAGenPartlnformation instances to specify the parts to search for associates. 

The first two methods return a Vector of VAGenPartlnformation instances which 
are the associates of the specified parts which exist in the Workspace. The last 
two methods return a Vector of VAGenPartldentity instances which are the 
associates of the specified parts, and which may or may not exist in the 
Workspace. 



public static boolean copy Part ( 
String name, 
long type, 
Vector packages, 
String newName, 
Package newPackage) 

Make a copy of the VAGen part specified by the first three parameters. If 
newPackage is null, the copy will be placed in the same package as the 
original. Return a boolean indicating success or failure. 



public static boolean del etePart (String name, long type, Vector packages) 

Delete the VAGen part specified by the parameters. Return a boolean 
indicating success or failure. 



public static boolean editPart (VAGenPartldentity id) 
public static boolean editPart (String name, long type) 

Open a VAGen editor on the part specified by the parameter(s). Return a 
boolean indicating success or failure. 



public static VAGenExportResults exportParts( 

String name, 

long type, 

Vector packages, 

String fileName, 

boolean append) 
public static VAGenExportResults exportParts( 

Vector parts, 

String fileName, 

boolean append) 

Export the VAGen parts specified by the name, type, and packages parameters 
of the first method, or the parts parameter of the second method. Parts are 
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exported in VAGen External Source Format (ESF) to the file specified by 
fileName. The append parameter indicates whether an existing file should be 
appended to or over-written. 



public static VAGenlmportResults importParts( 

String fileName, 
Package pkg, 
int confl ictResolution, 
boolean noBypass) 

Import the VAGen parts from the ESF file specified by fileName into the 
specified Package. The conflictResolution parameter is one of four value 
specifying what to do if a part already exists in the Workspace. See the import 
fields in the VAGenConstants class for valid values. See the help for the VAGen 
Import facility for more information on the meaning of the values. A value of 
true for the noBypass parameter indicates that no parts should be imported if 
there are errors parsing the ESF file. 



public static boolean movePart (String name, long type, Vector packages, 
Package newPackage) 

Move the specified part to the new package. Return a boolean indicating 
success or failure. 



public static void openPartsBrowser(String name, Vector parts) 

Open a VAGen Parts Browser with the given window title on the set of 
specified parts. The parts parameter is a Vector of VAGenPartlnformation 
instances. 



public static VAGenPartlnformation partInfo(String name) 
public static VAGenPartlnformation partInfo(String name, long type) 
public static VAGenPartlnformation partInfo(String name, long type, Vector 
packages) 

Return a VAGenPartlnformation instance representing the part which matches 
the specified parameters. If no part matches, null is returned. 



public static Vector partlnfos (String name) 

public static Vector partlnfos (String name, long type) 

public static Vector partlnfos (String name, long type, Vector packages) 
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Return a Vector of VAGenPartlnformation instances representing parts which 
match the specified parameters. If no parts match, an empty Vector is 
returned. 



public static boolean printParts (String name, long type, Vector packages) 
public static boolean printParts (Vector parts) 

Print the parts specified by the parameters. Return a boolean indicating 
success or failure. 



public static Vector referencesToPart(VAGenPartIdentity partld, Vector 
partsToSearch) 

public static Vector referencesToPart (String name, long type, Vector 
partsToSearch) 

Return a Vector of VAGenPartlnformation instances of the parts that reference 
the specified part. The partsToSearch Vector contains VAGenPartlnformation 
instances and specifies which parts should be searched for references. The 
parts to search do not need to be loaded in the Workspace. 



public static boolean renamePart (String name, long type, Vector packages, 
String newName) 

Rename the specified part to the new name. Return a boolean indicating 
success or failure. 



Supporting classes 

The supporting classes are: 

• VAGenConstants class 

• VAGenActionEvent class 

• VAGenPartldentity class 

• VAGenPartlnformation class 

• VAGenExportResults class 

• VAGenlmportResults class 

• VAGenlmportMessage class 

The following sections describe the supporting classes and the 
VAGenActionListener interface. 
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VAGenConstants class 



The VAGenConstants class defines the following set of static fields for use with 
the other APIs in the package. The IMPORT constants are used with the 
VAGenlltilitylnterface.importParts method. The MENU_ENABLED contants are 
used with the menu addition methods. The PART_TYPE constants are used to 
specify and identify VAGen part types in a variety of methods in the package. 
The PART_TYPE constants are long integers and can be bitwise-or'd together 
to produce a mask matching several types. 

IMPORT_DEFINED 

IMP0RTJI0NE 

IMPORT_TARGET 

IMPORT_TARGET_ONLY 

MENU_ENABLED_ALWAYS 

MENU_ENABLED_ONE_OR_MORE_SELECTED 

MENU_ENABLED_ONE_SELECTED 

MENU_ENABLED_TWO_SELECTED 



PART 


TYPE 


all 


part" 


"type" 


"ALL 4GL 


part" 


"type" 


"bindcontrol 


part" 


"type" 


"dataitem 


part" 


"type" 


"function 


part" 


"type" 


"linkage 


part" 


"type" 


"linkedit 


part" 


"type" 


"map 


part" 


"type" 


"mapgroup 


part" 


"type" 


"NON 4GL 


part" 


"type" 


"options 


part" 


"type" 


"program 


part" 


"type" 


"PSB 


part" 


"type" 


"record 


part" 


"type" 


"resources 


part" 


"type" 


"table 



PART_TYPE_ALL matches all parts. PART_TYPE_ALL_4GL matches data items, 
functions, maps, map groups, programs, PSBs, records, and tables. 
PART_TYPE_NON_4GL matches bind control, linkage, link edit, generation 
options, and resource association parts. 



VAGenActionListener interface 

When adding menu items to the VAGen Parts Browser, the class that receives 
the menu selection events must implement the VAGenActionListener interface. 

public void act ion Performed (VAGenAct ion Event e) 

This method is called when a menu item that has been added to the VAGen 
Parts Browser is selected. The VAGenActionEvent instance contains 
information about the event. 
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VAGenActionEvent class 



Instances of this class contain information about menu events that occur when 
menus items that have been added to the VAGen Parts Browser are selected, 
public String getActionCommand() 

Return the name of the menu item that was selected. 



public Object getActionData() 

Return an object with data specific to the type of menu that was selected. For 
menu items that were added to the VAGen Parts menu, this will return a 
Vector of VAGenPartlnformation instances corresponding to the VAGen parts 
currently selected in the browser. For items added to the Tools menu, this will 
return null. 



VAGenPartldentity class 

Instances of VAGenPartldentity are used to describe VAGen parts, and are 
returned from various VAGenUtilitylnterface methods. 

public String getName() 

public void setName (String newName) 

Return or set the name of the part. 



public long getType() 

public void setType(long newType) 

Return or set the type of a part. Types are long integers. The VAGenConstants 
class contains static fields identifying all the VAGen part types. 



public String getTypeString() 

Return a String representing the part type. 



public static native String getTypeString(long type) 

This is a static method which returns a String representation of the part type 
given a long integer. 
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VAGenPartlnformation class 

VAGenPartlnformation extends VAGenPartldentity. Instances are used to describe 
VAGen parts, and are returned from various VAGenUtilitylnterface methods. 

public String getDescription() 

public void setDescription(String newDescription) 

Get or set the description of the part. 



public String getESFString() 

Return the External Source Format (ESF) representation of the part. 



public Model getPackage() 

public void setPackage (Model pkg) 

Get or set the package which contains the part. Model is either a Package or 
PackageEdition instance, both of which are defined in the com.ibm.ivj.util.base 
package. See the VAJava help for more information on the VAJava Tool 
Integration classes. 



public Date getPreviousTimeStampO 

Return the timestamp of the previous edition of the part. If no previous 
edition exists, return null. 



public String getSubtypeString() 

public void setSubtypeString (String newSubtypeString) 

Get or set the subtype String of the part. 



public Date getTimeStampO 

public void setTimeStamp(Date newTimeStamp) 

Get or set the timeStamp of the part. 



public Date[] getTimeStamps() 

Return an array of timestamps representing the editions of the part. 
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public boolean loadEdition(Date timestamp) 

Load the edition of the part specified by the timestamp. Return true if the 
operation succeeded. 

VAGenExportResults class 

An instance of the VAGenExportResult class is returned from the 
VAGenlltilityConstants.exportParts methods, 
public int getReturnCode() 

Returns an integer indicating whether the export was successful. 
0 Success 

4 Some parts were exported successfully 

8 No parts were exported successfully. 

public String getMessageNumber () 

For non-zero return codes, getMessageNumber returns a String representing the 
message number. 

public String getMessageText() 

For non-zero return codes, getMessageText returns a String indicating the error. 

VAGenlmportResults class 

An instance of the VAGenlmportResult class is returned from the 
VAGenUtilityConstants.importParts method, 
public int getReturnCode() 

Returns an integer indicating whether the import was successful. 
0 Success 

4 Some parts were imported successfully 

8 No parts were imported successfully. 

public Vector getParseMessages() 
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Return a Vector of VAGenlmportMessage instances, representing the messages 
generated during parsing of the ESF file. 



public Vector get ImportMes sages () 

Return a Vector of VAGenlmportMessage instances, representing the messages 
generated during import. 



VAGenlmportMessage class 

Instances of this class represent messages generated during parsing and 
import of an ESF file. 

public boolean isInfo() 
public boolean isError() 

Return a boolean indicating whether this message is informational or an error. 



public String getPartName() 

Return a String representing the name of the part to which the message 
applies. 



public long getPartType() 

Return a long integer representing the type of the part to which the message 
applies. 



public String getMessageNumberQ 
public String getMessageText() 

Return Strings containing the message number and text. 



public int getRow() 
public int getColumn() 

Return integers indicating the row and column in the ESF file to which the 
message applies. 
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Appendix D. Smalltalk APIs 



The Smalltalk APIs described in this section enable you to perform additional 
name validation, add menus to the VAGen Parts Browser and VisualAge 
Organizer, and provide an interface to the VAGen part utilities. 

Only methods categorized as Hpt-API are supported. Public methods not 
categorized as Hpt-API are not supported. 



Part name validation 

HptPartValidationHandler provides two class methods to add and remove 
callbacks that allow for additional part name validation beyond the standard 
VAGen validation. VAGen validates part names when new parts are created 
and when existing parts are referenced in other parts. 

addCallbackFor: receiver selector: selector 

removeCallbackFor: receiver 

If the part name meets standard VAGen validation rules, the receiver 
is sent the message specified by selector during part name validation. 
The selector must accept the following arguments: 

partName 

partName is a string part type. 

partType 

partType is an integer part type from the HptLibraryConstants 
pool dictionary. Several types can be logically or'd together. 

context 

context is an ENVY application. 

The method returns true if the name is valid and returns false if the 
name is not valid. 

The context is nil when the ENVY application is not known during 
part name validation. For example, when a main function is added to 
a program, the function name is validated. In this example, the ENVY 
application of the function is not known. 

Part names are not validated during VAGen Import. You can create 
parts during import that do not meet the validation criteria of the 
callback methods. 
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Only one callback can be added for a given receiver. The following is 
an example validation method. 

sampleValidate: partName type: partType context: context 
"Ensure data item names end in ITEM" 

( partType allMask: HptLi braryConstants : : PartTypeDataltem ) 
if True: [ 

( partName copyFrom: partName size - 3 to: partName size ) = 'ITEM' 
ifFalse: [ "false ] ] . 

"Ensure all parts start with the same first three letters 
as their application." 
context isNil 
ifFalse: [ 

( partName copyFrom: 1 to: 3 ) = ( context name copyFrom: 1 to: 3 ) 
ifFalse: [ "false ] ] . 

true 



VAGen Utilities 

VAGenlltilitylnterface provides several class methods and interfaces to the 
VAGen part utilties. See "Supporting classes, methods and pools" on page 402 
for descriptions of the supporting classes, methods, and pools. The methods 
described here can be used with the EXECUTE batch command. For 
additional information on the EXECUTE command, see VisualAge Generator 
User's Guide. 



partNamed: patternString 

partNamed: patternString type: anlnteger 

partNamed: patternString type: anlnteger contexts: aContextCollection 

The partNamed: methods return an HptPartlnformation instance 
describing the part matching the criteria. 

patternString 

See the EsString»match: method for details on patternString 
matching. 

anlnteger 

anlnteger is a bitwise or'ing of part types from the 
HptLibraryConstants pool dictionary. 

aContextCollection 

aContextCollection is a collection of ENVY applications, nil 
may be used to match any application in the image. 

nil is returned if no part matches the criteria. 
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Examples: 

VAGenUtility Interface partNamed: ' EMPLOYE 1 . 
VAGenUtilitylnterface partNamed: ' EMPDATA ' type: 
HptLibraryConstants : : PartTypeRecord. 



partsNamed: patternString 

partsNamed: patternString type: anlnteger 

partsNamed: patternString type: anlnteger contexts: aContextCollection 

The partsNamed methods are similar to the partNamed methods 
except these return a collection of HptPartlnformation instances 
describing all parts matching the criteria. An empty collection is 
returned if there is no match. 

Examples: 
VAGenUtilitylnterface partsNamed: '*'. 

VAGenUtilitylnterface 
partsNamed: 'E* 1 

type: HptLibraryConstants: : PartTypeProgram | 
HptLi braryConstants : : PartTypeRecord . 

VAGenUtilitylnterface 
partsNamed: '*' 

type: HptLibraryConstants : : PartTypeAl 1 
contexts: ( Array with: HptSampl eEzerempParts 
with: HptSampl eStaff Parts ). 

aContextCollection for the partNamed and partsNamed methods is a 
collection of ENVY applications. These can be instances of Application 
or Sub Application that describe applications currently loaded in the 
image. They can also be instances of EmShadow Application or 
EmShadowSub Application that describe applications that are not 
currently loaded. aContextCollection does not need to be 
homogenous, it can contain a mixture of loaded and non-loaded 
applications. 

The following example uses an ENVY API to return a collection of 
shadow applications, representing the editions of 

HptSampleEzerempParts in the library. The VAGenUtilitylnterface API is 
then used to list the VAGen parts in the latest application edition. 
| shadowApps | 

shadowApps := Application shadowsFor: 'HptSampleEzerempParts'. 
VAGenUtilitylnterface 
partsNamed: '*' 

type: HptLibraryConstants: :PartTypeAll 
contexts: ( Array with: shadowApps first ) 
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associatesOfPartsNamed: patternString type: anlnteger 
contexts: aContextCollection 

associatesOfParts: aPartCollection 

idAssociatesOfPartsNamed: patternString type: anlnteger 
contexts: aContextCollection 

idAssociatesOfParts: aPartCollection 

These methods return a collection of associate parts of the parts 
matching the critieria or of the parts in aPartCollection. If no parts 
match the criteria, an empty collection is returned. 

patternString 

See the EsString»match: method for details on patternString 
matching. 

anlnteger 

anlnteger is a bitwise or'ing of part types from the 
HptLibraryConstants pool dictionary. 

aContextCollection 

aContextCollection is a collection of ENVY applications, nil 
may be used to match any application in the image. 

aPartCollection 

aPartCollection must be a collection of HptPartlnformation 
instances. 

The associatesOfPartsNamed: and associatesOfParts: methods return 
a collection of HptPartlnformation instances for associate parts that are 
loaded in the image. The idAssociatesOfPartsNamed: and 
idAssociatesOfParts: methods return a collection of HptPartldentity 
instances for all associate parts, regardless of whether they are loaded 
in the image. 

Examples: 

VAGenUtilitylnterface 
associatesOfPartsNamed: '*' 
type: HptLibraryConstants: : PartTypeRecord 
contexts: ( Array with: HptSampl eEzerempParts ). 

| aPartlnfo [ 

aPartlnfo := VAGenUtilitylnterface partNamed: ' EMPLOYE 1 . 
VAGenUtilitylnterface idAssociatesOfParts: ( Array with: aPartlnfo ). 

associatesOfClasses: aClassCollection 
idAssociatesOfClasses: aClassCollection 
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These methods return a collection of associate VAGen parts of the 
classes in aClassCollection. 

aClassCollection 

The classes are VisualAge Smalltalk visual or non-visual parts 
that contain VAGen parts. 

The associatesOfClasses: method returns a collection of 
HptPartlnformation instances for those associate parts that are loaded 
in the image. The idAssociatesOfClasses: method returns a collection 
of HptPartldentity instances for all associate parts, regardless of 
whether they are loaded in the image. An empty collection is returned 
in both cases if the classes have no associate VAGen parts. 

Example: 

VAGenUti 1 i ty Interface associatesOfClasses: ( Array with: HptSampleView ) 
editPart: aPartlnfo 

editPartNamed: partName type: anlnteger 

These methods open a VAGen editor on the specified part. 
aPartlnfo 

aPartlnfo is an instance of HptPartlnformation representing a 
part to be edited. 

partName 

partName cannot contain any wildcard characters and the 
part must exist in the image. 

anlnteger 

anlnteger is a bitwise or'ing of part types from the 
HptLibraryConstants pool dictionary. 

A boolean is returned indicating whether the editor opened 
successfully. 

openBrowserNamed: titleString on: aPartCollection 

This method opens a VAGen Parts Browser with the specified title on 
the named collection of parts. After the browser is open, you can filter 
and sort the parts, and invoke VAGen utilities on the parts. You can 
open a browser on a collection of parts that is not currently loaded in 
the image. For parts not loaded in the image, you cannot filter by 
application. 
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titleString 

titleString is the title of the browser. 

aPartCollection 

aPartCollection must be a collection of HptPartlnformation 
instances. 

importFileNamed: aFileName toApplication: 

anApplication conflictResolution: anlnteger noBypass: aBoolean 

Import the parts from the ESF file specified by aFileName into the 
ENVY application, anApplication. 

aFileName 

An ESF file containing parts to be imported 

anApplication 

The ENVY application to contain the imported parts 

anlnteger 

anlnteger is either ImportNone, ImportDefined, ImportTarget, 
or ImportTargetOnly. These keys are defined in the 
HptUtilityConstants pool and correspond to the options 
available from the interactive Import command as well as the 
IMPORT batch command. 

aBoolean 

If aBoolean is true and parsing errors occur, no parts are 
imported. 

An instance of HptlmportResults is returned from this method. 

exportPartsNamed: patternString type: anlnteger 

contexts: aContextCollection toFileNamed: aFileName 
append: aBoolean 

exportParts: aPartCollection toFileNamed: aFileName append: aBoolean 

These methods export the VAGen parts matching the specified 
criteria, or those specified by aPartCollection. 

patternString 

See the EsString»match: method for details on patternString 
matching. 

anlnteger 

anlnteger is a bitwise or'ing of part types from the 
HptLibraryConstants pool dictionary. 
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aContextCollection 

aContextCollection is a collection of ENVY applications, nil 
may be used to match any application in the image. 

aPartCollection 

aPartCollection is a collection of HptPartlnformation instances. 

aFileName 

The parts are exported to the ESF file specified by aFileName. 
aBoolean 

If aBoolean is true and the file already exists, the parts are 
appended to the file. Otherwise, the contents of the file are 
replaced. 

You can export parts that are not currently loaded in the image. 
An instance of HptExportResults is returned from these methods. 

copyPartNamed: partName type: partType contexts: aContextCollection 
newName: newName newContext: newContext 

This method is used to copy the part matching the name, type, and 
context criteria to the new name. If newContext is nil, the new part 
will be copied to the same application as the original. Return true if 
the part was copied successfully. 

partName 

partName is the name of the part. 

partType 

partType is an integer from the HptLibraryConstants pool 
dictionary. 

aContextCollection 

aContextCollection is a collection of ENVY applications, nil 
may be used to match any application in the image. 

newName 

newName is the new name of the part. 

newContext 

newContext is the name of the target ENVY application. If 
newContext is nil, the new part will be copied to the same 
application as the original. 

deletePartNamed: partName type: partType 

This method is used to delete the specified part from the library. 
Return true if the part was deleted successfully. 
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partName 

partName is the name of the part. 

partType 

partType is an integer from the HptLibraryConstants pool 
dictionary. 

movePartNamed: partName type: partType 

contexts: aContextCollection newContext: newContext 

This method is used to move the specified part to the new 
application, specified by newContext. Return true if the part was 
moved successfully. 

partName 

partName is the name of the part. 

partType 

partType is an integer from the HptLibraryConstants pool 
dictionary. 

aContextCollection 

aContextCollection is a collection of ENVY applications, nil 
may be used to match any application in the image. 

newContext 

newContext is the name of the target ENVY application. 
printParts: aPartCollection 

printParts: aPartCollection printManager: printManager 

printPartsNamed: patternStringType: anlnteger 
contexts: aContextCollection 

printPartsNamed: patternStringType: anlnteger 

contexts: aContextCollection printManager: printManager 

These methods print the parts specified by aPartCollection, or that 
match the name, type, and context criteria. printManager is an 
instance of CivTextPrintingManager. If it is not specified, the parts will 
be printed to the currently selected printer. If no printer is selected, a 
prompt will be displayed. 

patternString 

See the EsString»match: method for details on patternString 
matching. 

anlnteger 

anlnteger is a bitwise or'ing of part types from the 
HptLibraryConstants pool dictionary. 
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aContextCollection 

aContextCollection is a collection of ENVY applications, nil 
may be used to match any application in the image. 

aPartCollection 

aPartCollection is a collection of HptPartlnformation instances. 

printManager 

printManager is an instance of CwTextPrintingManager. 

referencesToPartNamed: partName type: partType in: aPartCollection 
showProgress: aBoolean 

referencesToPart: aPartID in: aPartCollection showProgress: aBoolean 

These methods return the collection of parts that reference the given 
part. 

partName 

partName cannot contain any wildcard characters 
partType 

partType must be an Integer representing a single part type. 

aPartCollection 

aPartCollection is a collection of HptPartlnformation instances 
representing the parts to be searched for references. 

aPartID 

aPartID is an HptPartldentity instance representing the part to 
search for. 

aBoolean 

aBoolean specifies whether to show a progress dialog while 
the search is being performed. 

Examples: 

| partsToSearch | 
partsToSearch := 

VAGenUti 1 itylnterface partsNamed: '*' type: 
HptLibraryConstants : : PartTypeFunction. 
VAGenUti 1 itylnterface 

referencesToPartNamed : ' EMPDATA ' 

type: HptLibraryConstants: : PartTypeRecord 

in: partsToSearch 

showProgress: true 

The parts to be searched do not need to be currently loaded in the 
image. The following example searches all VAGen parts in all 
applications within the most recent edition of the configuration map 
named MyMap. 
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I appsToSearch partsToSearch | 
appsToSearch := 

( EmConfigurationMap editionsFor: 'MyMap' ) 
first shadowAppl i cations. 
partsToSearch := 
VAGenUtilitylnterface 
partsNamed: '*' 

type: HptLibraryConstants: :PartTypeAl 1 

contexts: appsToSearch. 
VAGenUtilitylnterface 

referencesToPartMamed: ' EMPDATA' 

type: HptLibraryConstants: : PartTypeRecord 

in: partsToSearch 

showProgress : true 

The following code creates a list of applications to search. Version 1.0 
of applications MyAppl, MyApp2, and MyApp3 will be searched. The 
rest of the search code is the same as the example above. 

| appsToSearch | 
appsToSearch := 
#( 'MyAppl' 'MyApp2' 'MyApp3' ) 
collect: [ :anApp | 

( Application shadowsFor: anApp ) 
detect: [ :aShadowApp | 
aShadowApp isVersion and: [ aShadowApp versionName = '1.6' ] ] ]. 



Adding menus to the Parts Browser 

The following class methods in the VAGenUtilitylnterface class allow menus 
to be added to the VAGen Parts Browser and VisualAge Organizer. 

Menu items and separators will appear in the order they are added. Menu 
additions will be saved in the image, so the code to add the items only needs 
to be executed once. 

addPartsMenuItemNamed: aName receiver: aReceiver selector: aSelector 
enabled: anlnteger 

Add a menu item to the VAGen Parts menu of the VAGen Parts 
Browser and VisualAge Organizer. 

aName specifies the name of the menu to be added. A tilde character 
( ) can be placed before one of the characters in aName to indicate the 
menu mnemonic. The menu item will be added to a Tools cascade 
menu off the VAGen Parts menu. aReceiver specifies the object which 
will be sent a message when the menu is selected, and aSelector 
specifies the message to be sent. The method that is invoked when the 
menu is selected must take two arguments: the name of the menu 
item selected, and an OrderedCollection of the VAGen Parts that are 
currently selected, anlnteger specifies when the menu item should be 
enabled. Use one of the contants in the HptUtilityConstants pool 
dictionary to specify menu enablement. 
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The following example code adds a menu item named 'Test', with T 
as the menu mnemonic. The class method 

#partsMenuSelectedNamed:parts: of class MyMenuHandler will be 
invoked when the menu item is selected. The menu item will be 
enabled when one or more VAGen Parts are selected. 

VAGenUti 1 i ty Interface addPartsMenuItemNamed : 1 Test 1 
receiver: MyMenuHandler 
sel ector : IpartsMenuSel ectedNamed : parts : 

enabl ed : HptUti 1 i tyConstants : :MenuEnabl edWhenOneOrMoreltemsSel ected . 

addPartsMenuSeparatorNamed: aName 

Add a menu item separator to the VAGen Parts menu of the VAGen 
Parts Browser and VisualAge Organizer. 

The separator will be added to the Tools cascade menu of the VAGen 
Parts menu. 

addToolsMenuItemNamed: aName receiver: aReceiver selector: aSelector 

Add a menu item to the Tools menu of the VAGen Parts Browser. 

aName specifies the name of the menu to be added. A tilde character 
( ) can be placed before one of the characters in aName to indicate the 
menu mnemonic. aReceiver specifies the object which will be sent a 
message when the menu is selected, and aSelector specifies the 
message to be sent. The method that is invoked when the menu is 
selected must take one argument: the name of the menu item selected. 

The following example code adds a menu item named 'Test', with T 
as the menu mnemonic. The class method #toolsMenuSelectedNamed: 
of class MyMenuHandler will be invoked when the menu item is 
selected. 

VAGenUti 1 i ty Interface addToolsMenuItemNamed: 1 Test 1 
receiver: MyMenuHandler 
selector: ItoolsMenuSel ectedNamed: . 

addToolsMenuSeparatorNamed: aName 

Add a menu item separator to the Tools menu of the VAGen Parts 
Browser. 

removePartsMenuItemNamed: aName 

Remove the menu item or separator named aName from the VAGen 
Parts menu of the VAGen Parts Browser and VisualAge Organizer. 

If a mnemonic character was specified when the menu item was 
added, do not include it in the name when removing the menu item. 
Return true if the menu item was removed successfully and false if 
not. 

removeToolsMenuItemNamed: aName 

Remove the menu item or separator named aName from the Tools 
menu of the VAGen Parts Browser. 
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If a mnemonic character was specified when the menu item was 
added, do not include the tilde character in the name when removing 
the menu item. Return true if the menu item was removed 
successfully and false if not. 



Supporting classes, methods and pools 

HptLibraryConstants pool dictionary 

This pool dictionary defines the following part type keys. These are integer 
values and can be or'd together to produce a part type criteria to be used in 
the VAGenUtilitylnterface methods. 

• PartTypeAll 

• PartTypeA114GL 

(all except Options, Linkage, Resources, BindControl and LinkEdit) 

• PartTypeNon4GL 

(only Options, Linkage, Resources, BindControl and LinkEdit) 

• PartTypeProgram 

• PartTypeDataltem 

• PartTypeMapGroup 

• PartTypeMap 

• PartTypeFunction 

• PartTypePsb 

• PartTypeRecord 

• PartTypeStatementGroup 

• PartTypeTable 

• PartTypeOptions 

• PartTypeLinkage 

• PartTypeResources 

• PartTypeBindControl 

• PartTypeLinkEdit 

HptLibraryConstants also defines the following dictionaries, used to convert 
between part type integer and string values: 



Table 19. HptLibraryConstants Dictionaries 



Dictionary 


Keys 


Values 


PartTypelntegers 


part type strings 


part type integers 


PartTypeStrings 


part type integers 


part type strings 


PartTypeBatchStrings 


part type integers 


part type batch string 






abbreviations 



HptUtilityConstants pool dictionary 

This pool dictionary defines keys used in several of the VAGenUtilitylnterface 
methods. 
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Specify one of the following keys for conflictResolution with the 
VAGenUtilitylnterface import API: 

• ImportNone 

• ImportDefined 

• ImportTarget 

• ImportTargetOnly 

Use the following keys to specify when menu items added to the VAGen 
Parts menu are enabled: 

• MenuEnabledAlways 

• MenuEnabledWhenOneOrMoreltemsSelected 

• MenuEnabledWhenOneltemSelected 

• MenuEnabledWhenTwoItemsSelected 

Part information hierarchy 

Instances of the following classes describe the parts returned from various 
VAGenUtilitylnterface methods. The class hierarchy is as follows: 

HptPartldentity 
HptPartLocation 
HptPartEdition 
HptPartlnformati on 



The following methods are the public APIs of each class. 
Table 20. Public APIs 



Class 


Method 


Description 


HptPartldentity 


name 


get the part name 




name: 


set the part name 




type 


get the part type (Integer) 




type: 


set the part type 




typeString 


get the part type (String) 


HptPartLocation 


context 


get the part context (ENVY 
application) 




context: 


set the context 




contextName 


set the name of the context 
(String) 


HptPartEdition 


timeStamp 


get the time stamp 
(EmTimeStamp ) 


HptPartlnformation 


description 


get the part description 




developer 


get the part developer 
(EmUser) 




developerName 


get the developer name 
(String) 
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Table 20. Public APIs (continued) 



Class 


Method 


Description 




esfString 


get the ESF representation 
of the part (String) 




subtypeString 


get the part subtype 
(String) 




subtypeString: 


set the part subtype 




typeAndSubtypeString 


get a string with the part 
type and subtype 



Note: For VAGenUtilitylnterface methods that take a collection of 

HptPartlnformation instances, the instances cannot be created using the 
setter methods above. The instances should be created using the 
partNamed and partsNamed methods, as well as the part associate 
methods. 

The following example uses the esfString method to search all parts in 
application HptSampleEzerempParts and open a browser on those parts 
whose ESF contains the string "EZEMSG." 

| searchString appsToSearch partsToSearch matchi ngParts | 
searchString := 'EZEMSG'. 
appsToSearch := 

Array with: ((Application shadowsFor: 'HptSampleEzerempParts') first). 
partsToSearch := 
VAGenUtilitylnterface 
partsNamed: '*' 

type: HptLi braryConstants : :PartTypeAll 
contexts: appsToSearch. 
matchingParts := 

partsToSearch select: [ :partInfo | 
( partlnfo esfString 

indexOfSubCollection: searchString startingAt: 1 ) = 0 ]. 
VAGenUtilitylnterface 
openBrowserNamed: 'Search Results' on: matchingParts. 

Hpt Export Results 

An instance of this class is returned from the VAGenUtilitylnterface export 
methods. The class has the following public APIs: 

messageNumber 

a string representing the message number 

messageText 

a string describing the error 
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returnCode 

returnCode is an integer. For non-zero returnCodes, messageText will 
contain a string indicating the error. 

0 Indicates success 

4 Indicates some parts were exported successfully 

8 Indicates no parts were exported successfully. 

HptlmportResults 

An instance of this class is returned from the VAGenUtilitylnterface import 
method. The class has the following public APIs: 

importErrors 

returns a collection of HptlmportMessage instances, describing the 
errors that occurred during the import. 

parseErrors 

returns a collection of HptlmportMessage instances, describing the 
errors that occurred during the parse. 

returnCode 

returnCode is an integer. 

0 Indicates success 

4 Indicates some parts were imported successfully 

8 Indicates no parts were imported successfully 
HptlmportMessage 

Instances of this class describe an error that occurred during import. The class 
has the following public APIs: 

islnfo returns true if this is an informational message 
isError 

returns true if this is an error message 

messageNumber 

a string representing the message number 

messageText 

a string describing the error 

partName 

name of part the error occurred on 

partType 

type of part the error occurred on 

row row in ESF file where parse error occurred 
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column 

column in ESF file where parse error occurred 

Integer 

For Integers representing VAGen part types, the hptPartTypeString method 
returns a String representation of the part type. 

EmTimeStamp 

The following methods can be used to convert between Date and Time 
instances and EmTimeStamp instances: 

hptFromDateAndTime: 

This class method returns a new EmTimeStamp instance created from 
an array of Date and Time instances 

hptDate 

Return a Date instance matching the receiver's date 
hptTime 

Return a Time instance matching the receiver's time 
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Appendix E. Program Control Linkage Conventions 



This section describes the programming elements that enable you to define 
statements that transfer control among VisualAge Generator programs 
generated as COBOL and C++ programs and user-written programs. The term 
generated program refers to programs developed using VisualAge Generator. 

Programs or non- VisualAge Generator programs are programs written in a 
language such as COBOL or Assembler. This does not include programs 
developed with VisualAge Generator that are generated into COBOL 
programs. You can use the CALL, XFER, or DXFR statements to transfer 
control among programs. 

A CALL statement transfers control to a generated program or a 
non-VisualAge Generator program and returns to the originating program. Up 
to 30 parameters (maps, records, level-77 data items, and literals) can be 
passed so that data can be accessed by multiple programs. Figure 37 on 
page 408 shows the control path of a program using a CALL statement. 
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407 



Note: The called program returns to the original program when the program 

logic ends or when EZECLOS is issued. 
XFER and DXFR statements transfer control to a program without returning 

CALL 




Figure 37. Control Path of Program Using CALL Statement 

to the originating program. Any record can be passed to a program, but it is 
received into the primary working storage record of the target program of an 
XFER or DXFR statement. You can also pass a map with an XFER statement. 
Figure 38 on page 409 shows the control path of programs using XFER and 
DXFR statements. 
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Figure 38. Control Path of Program Using XFER and DXFR Statements 



When a program calls or transfers to a generated program or is called or 
transferred to by a generated program, the program must use the same call or 
transfer linkage conventions used by the generated program. The 
implementation of call and transfer in the generated program depends on the 
run-time environment, the generation options, and the linkage specified for 
the program in the linkage table. 

For more information on linkage tables, refer to VisualAge Generator 
Client/Server Communications Guide. See the environment-dependent sections in 
this chapter for detailed information on call and transfer interfaces used by 
generated programs. 

Read the design considerations in this chapter before defining VisualAge 
Generator programs that use a CALL, XFER, or DXFR statement. Refer to the 
VisualAge Generator Design Guide document for additional information. 



Design Considerations 

When you design programs, you can choose to transfer control with CALL, 
DXFR, and XFER statements. This section contains residency and design 
considerations for the CALL, DXFR, and XFER statements. 

Residency Considerations for CICS Programs 

The method you use to transfer control affects the residency of your 
programs. VisualAge Generator generates re-entrant COBOL programs, tables, 
mapping services programs, and map group format object modules. Any of 
these programs can be made resident in storage by using the standard 
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residency functions provided in the operating environment (for example, MVS 
Link Pack Area, VSE Shared Virtual Area, IMS preload, or defining a program 
as resident to CICS). 

If a program is not marked as resident, the length of time it remains in 
storage depends on the type of program and the operating environment. You 
can usually assume that programs, tables, mapping service programs, and 
map group format modules loaded by COBOL, VisualAge Generator Server 
for MVS, VSE, and VM, or VisualAge Generator Server, including programs 
transferred to with a DXFR statement, remain loaded until the end of the run 
unit (or on IMS, until the last message on the message queue is processed). 

Programs started by CICS LINK or CICS XCTL commands are released by 
CICS according to normal CICS conventions. Reentrant programs loaded by 
CICS remain in storage until the storage is required for another program. This 
effectively makes a program resident on XA and ESA the first time it is 
loaded. 

When table programs are loaded for CICS by VisualAge Generator Server for 
MVS, VSE, and VM, the table contents are copied into dynamic storage so that 
they can be modified by the program, and the table program is deleted 
immediately. 

The Resident table option specified when you defined the table applies to the 
copy of the table in dynamic storage and not to the table program. The 
reentrant table program can still be made resident using the CICS residency 
functions. 

Design Considerations for CALL Statements 

The following are design considerations for VisualAge Generator CALL 
statements grouped into program definition and run-time considerations. 

Program Definition Considerations 

The following list contains program definition design considerations for 
VisualAge Generator CALL statements: 

• The CALL statement can only be used within a process or statement group. 
It cannot be coded in the flow stage of a program. 

• Programs that are the object of a CALL statement must be defined as called 
programs with parameters that are compatible with the arguments specified 
on the CALL statement. When the called program ends, the calling program 
resumes at the statement following the CALL. 

• When you define a called program, you must list the received parameters 
in the called parameter list. The names in the parameter list must be 
defined in the library as records, maps, or data items. You must list the 
parameters in the same order as they appear on the CALL statement in the 
calling program. The parameters in the receiving program must also match 
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the passed arguments' data type, structure, and length. If the called 
parameter list does not exactly match the passed arguments, the results of 
the CALL statement are unpredictable. To ensure the parameters exactly 
match it is recommended that you use the same argument names on the 
CALL statement and on the called parameter list. 

• Names in the called parameter list must not be defined in the called 
program in any other way (that is, as objects of processes, as data items in 
working storage, or as data items in another structure). 

• Define a character literal argument as a data item parameter in the called 
program. 

• When you specify a working storage record as an argument on a CALL 
statement, only the record structure is passed. Level-77 data items must be 
passed as separate arguments. 

• Data items that are passed as separate arguments must be Level 77. 

• When a non-VisualAge Generator program is called, the return code from 
the called program is not available to the calling program. Use a parameter 
for returning status information to the calling program. 

VisualAge Generator Server for MVS, VSE, and VM or VisualAge 
Generator Server Runtime Considerations 

The following list contains run-time design considerations for VisualAge 
Generator CALL statements: 

• If non- VisualAge Generator programs are called, VisualAge Generator 
Server for MVS, VSE, and VM or VisualAge Generator Server lose program 
control, and you are responsible for returning control and maintaining the 
integrity of the storage area passed to the called program. 

• On AIX, 2-byte binary fields must be aligned on a 2-byte boundary and 
4-byte binary fields must be aligned on a 4-byte boundary. If these fields 
are not aligned correctly, the compiler automatically pads the fields so they 
are properly aligned. You must consider this when passing parameters from 
an AIX system to a non- AIX system and vice versa. 

SQL row records should not be passed as a parameter from an AIX system 
to a non- AIX system and vice versa because each field in an SQL row 
record contains an additional 4 bytes of data. These additional 4 bytes must 
be aligned on an even-byte boundary. For more information on these 
additional 4 bytes, refer to the VisualAge Generator Design Guide document. 

• Map areas passed are defined with 8 bytes of adjunct fields preceding each 
field data content area (see Figure 39 on page 412). The first 6 bytes of the 
adjunct field are set to blanks. The last 2 bytes of the adjunct field contain 
the length of the data. The field length is set to the length of the field 
defined in the map. It does not include the 8-byte prefix. 

If the receiving structure in the called program is not a map, the structure 
should have space for the 8 bytes before each data item. 
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The only changes that can be made to a passed map by a called program 
are to the data in the variable fields. For example, the attributes of map 
variable cannot be changed by a called program. 



-8-byte - 



6 bytes 



2-byte length 



data for map field 



Figure 39. Diagram of Map Area Passed Using CALL Statement 

When passing a map as a parameter from an AIX system to a non-AIX 
system and vice versa, the 2-byte binary fields must be aligned on a 2-byte 
boundary, which starts at the third byte of the 8-byte field. 

• Because of some differences in the VisualAge Generator-supported 
environments that affect data set operations between called programs, 
VisualAge Generator process options for records (INQUIRY, SCAN, 
SCANBACK, UPDATE, REPLACE, CLOSE, DELETE) should not be used in 
a called program if those process options are accessing the same data sets 
in any of the calling programs. For example, if APPLA calls APPLB and 
APPLB then calls APPLC, a data set should not be accessed by APPLC if 
the same data set is accessed by APPLA or APPLB. A data set should not be 
accessed by APPLB if it is accessed by APPLA. 

• A VisualAge Generator main program and a called program can access the 
same DL/I databases by sharing the same PSB and passing EZEDLPSB or 
EZEDLPCB as a parameter on the CALL statement. Additionally the PSB 
can also be shared between VisualAge Generator programs and 

non- VisualAge Generator programs. Refer to the VisualAge Generator Design 
Guide document for a description of how called and calling programs can 
both access the same database. 

• Only Assembler or COBOL programs can be dynamically called from a 
COBOL program. For non-CICS environments, called PL/I programs and 
COBOL programs that call PL /I programs must be statically linked with 
the initial COBOL program. For CICS environments, a CICS LINK 
command must be used to call PL/ 1 programs. 

• For CICS for MVS/ESA or CICS for VSE/ESA, COBOL programs cannot be 
statically called by Assembler programs. 

• The EXEC DLI and CBLTDLI interfaces to DL/I databases cannot be mixed 
in the same transaction. Generated COBOL programs use the CBLTDLI 
interface because it is required for the CSPTDLI service. Therefore, 

non- VisualAge Generator programs must not use the EXEC DLI interface to 
DL/I databases if the program runs with generated DL/I programs in the 
same transaction. 

• Position for the SCAN, SCANBACK or REPLACE process options might be 
lost in a calling program if the called program accesses the same file. 
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• Programs that call programs linked to run with 24-bit addresses must be 
generated with the /DATA=24 generation option. 

Design Considerations for DXFR and XFER Statements 

The following list contains design considerations for the use of DXFR and 
XFER statements in Visual Age Generator programs: 

• In transactional environments (IMS and CICS) the XFER statement is a 
transfer from one transaction to another; the DXFR statement is a transfer 
between programs within the same transaction. Use DXFR for better 
performance; use XFER when you want to commit database changes on the 
transfer. 

• The transfer statement can be used in a process, flow, or a statement group. 

• Called programs cannot use DXFR or XFER to transfer to another 
VisualAge Generator program. 

• Level-77 data items are not included with a working storage record if it is 
passed. 

• The transferred-to program can only receive a record through the working 
storage record defined in the program specifications. It is not listed as a 
received parameter and the program itself must not be defined as a called 
program. 

• If non- VisualAge Generator programs are transferred to, the NONCSP 
option can be coded on the XFER statement in the program. 

• NONCSP is required for a transfer using a DXFR to a non- VisualAge 
Generator program. NONCSP can be specified either as an option on the 
DXFR or on the DXFRLINK tag in the linkage table. 

• XFER with a map option is supported in all online environments between 
VisualAge Generator programs. 

• To reduce overhead when doing a segmented CONVERSE in a program 
invoked through a DXFR statement, move a transaction name that is 
associated with the program to EZESEGTR prior to the CONVERSE 
process. If this is not done, the previous transaction is started when the 
terminal input is received and that program must then restore saved status 
and invoke the program that actually issued the CONVERSE process. 

• The value of EZEDEST is reset across DXFR and XFER operations. 

• XFER is not supported in the VSE batch environment. DXFR to a 
non- VisualAge Generator program is not supported in the VSE batch 
environment. 
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Appendix F. Transferring Control in the CICS Environment 



In the CICS environment, you can transfer program control using the CALL, 
DXFR, and XFER statements. 



Calls in the CICS Environment 

You use the linkage table to specify the type of linkage generated for a CALL 
statement. In the CICS environments, you can specify the following types of 
linkage: 
DYNAMIC 

Standard dynamic COBOL or C++ call 

STATIC 

Standard static COBOL or C++ call. On host systems, the called 
program must be link edited with the calling program. On 
workstations, the static call is implemented like a dynamic call; the 
program resides in a DLL or shared library. 
CICSLINK 

CICS LINK command (default for CICS programs) > 
REMOTE 

CICS LINK command; the called program can reside on a different 
system than the calling program. COMMDATA is the only valid 
parameter format for REMOTE linkage. 

All types except static linkage require the called program to be defined in the 
CICS PPT. 

You can also specify how the parameters on the CALL statement are passed to 

the receiving program: 

COMMPTR 

Pointers to the parameters are passed in the COMMAREA (default for 

CICS programs). 
COMMDATA 

Parameter data is passed in the COMMAREA. 
OSLINK 

Parameters are passed using a standard COBOL parameter list. The 
called program cannot contain any CICS statements or be a generated 
COBOL program. 
CICSOSLINK 

A standard COBOL parameter list is used. The first two parameters 
are the EIB and COMMAREA followed by the CALL statement 
parameters. CICSOSLINK is not supported for CICS for AIX. 
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Table 21 shows the valid parameter format and linkage combinations for 
CICS. 

Table 21. Valid Parameters and Linkages for CICS 





COMMPTR 


COMMDATA 


OSLINK 


CICSOSLINK 


DYNAMIC 


X 


X 


X 


X 


STATIC 


X 


X 


X 


X 


CICSLINK 


X 


X 


NO 


NO 


REMOTE 


NO 


X 


NO 


NO 


Note: X indicates the combination is valid. 



For additional information on the linkage table, refer to the VisualAge 
Generator Client/Server Communications Guide. 

All calls described here are local calls between programs running on the same 
CICS system. Called programs can also run on a different system than the 
calling program. These programs are defined as remote programs. For remote 
programs, a CICS LINK is performed with data passed in the COMMAREA 
control block (COMMDATA). For additional information on remote programs, 
refer to the VisualAge Generator Client/Server Communications Guide. 

On CICS for MVS/ESA or CICS for VSE/ESA, a CICS LINK must be used to 
call to and from PL/I programs. 

Calls from a Generated Program to a Generated Program 

The called program runs and returns control to the calling program when the 
program ends or an EZECLOS is encountered. Up to 30 parameters can be 
passed on the CALL. No CICS SYNCPOINT occurs as a result of a CALL. 

The linkage type and parameter format for a called program must be identical 
when generating both the calling and called program. If the linkage type or 
parameter format are changed, the called program and all programs that call 
it must be generated again. 

COMMAREA Pointer (COMMPTR) Parameter Format 

For the parameter format COMMPTR, pointers are passed in the CICS 
COMMAREA. The COMMAREA is generated in the calling program's 
COBOL working storage area. On MVS and VSE systems, the high-order bit is 
set on for the last parameter address in the COMMAREA for the parameter 
format COMMPTR. 

Figure 40 on page 417 illustrates the COMMPTR parameter format. Register 1 
points to a list of pointers. The first is the address of the EIB, followed by the 
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address of the COMMAREA. Pointers to the parameters are passed in the 
COMMAREA. 



Register 1 



► 


Address of EIB 


Address of COMMAREA 





High Order 
Byte, 
Bit 0 = 1 



1 ► 


4 Byle Parm Pointer 






► 


4 Byte Parm Pointer 


X'FFFFFFFF 





1 to 30 

Parameter 

pointers 



List End 
(optional - see 
note) 



Figure 40. COMMPTR Parameter Format 

Note: The X'FFFFFFFF' fullword at the end of the parameter list is consistent 
with the CSP/AE CALL interface. The length of the COMMAREA does 
not include this fullword unless /ENDCOMMAREA is specified as a 
COBOL generation option for the calling program. If the generation 
option /ENDCOMMAREA was specified and the parameter format 
COMMPTR is in effect, the length specified for COMMAREA on the 
EXEC CICS LINK command is automatically increased by 4 bytes. 
Under certain conditions, CICS passes a copy of the COMMAREA to 
the called program. Specify /ENDCOMMAREA to ensure that the 
X'FFFFFFFF' fullword is included when a copy of the COMMAREA is 
made. 



COMMAREA Data (COMMDATA) Parameter Format 

For the parameter format COMMDATA, the actual data is passed in a single 
buffer in the CICS COMMAREA. The COMMAREA is generated in the calling 
program's working storage area. Each parameter value is moved to the 
COMMAREA, where the values adjoin one another without regard for 
boundary alignment. If variable length records are passed, space is reserved 
for the maximum length record as defined to VisualAge Generator. If a 
variable length record with a record length item is passed, the item must be 
defined within the variable length structure. The called program must return 
the parameter values in the COMMAREA in the same order. The calling 
program moves the returned parameter values in the COMMAREA back to 
the original parameters. 
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Figure 41 illustrates the COMMDATA parameter format. Register 1 points to a 
list of pointers. The first is the address of the EIB, followed by the address of 
the COMMAREA. Actual parameter data is passed in the COMMAREA. 



Register 1 



► 


Address of EIB 






Address of COMMAREA 










Parameter Data 


> 



Figure 41. COMMDATA Parameter Format 

There are special considerations for the EZEDLPSB and EZEDLPCB 
parameters. If EZEDLPCB is passed as a parameter, it is implemented as a 
12-byte field consisting of an 8-byte PSB name followed by a 4-byte address. 
The address points to the CICS user interface block (UIB). EZEDLPCB is 
always passed using a 4-byte pointer because the called program must point 
to the actual DL/I PCB in DL/I calls. The called program cannot use a copy 
of the PCB. When COMMDATA is specified, the 4-byte pointer is moved into 
the COMMAREA at the position to be occupied by the EZEDLPCB argument. 



OSLINK Parameter Format 

For the parameter format OSLINK, the EIB and COMMAREA are not passed. 
Only the parameters specified on the CALL statement are passed. The 
high-order bit is set on for the last address in the parameter list for parameter 
format OSLINK. OSLINK is valid only for DYNAMIC and STATIC linkage 
types. The called program must not issue any EXEC CICS commands and 
cannot be a generated COBOL program. 

Figure 42 illustrates the OSLINK parameter format. Register 1 points to a list 
of pointers that are the addresses of buffers of parameter data (one for each 
parameter). 



Register 1 



High Order Byte, 
Bit 0 = 1 



4 Byte Parm Pointer 



4 Byte Parm Pointer 



1 to 30 parameter 
pointers 



Figure 42. OSLINK Parameter Format 
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CICSOSLINK Parameter Format 

For the parameter format CICSOSLINK, the EIB and COMMAREA are always 
passed as the first two parameters followed by the parameters specified on 
the CALL statement. CICSOSLINK is valid only for STATIC and DYNAMIC 
linkage types. DYNAMIC CICSOSLINK is valid only on CICS/ESA, CICS for 
VSE/ESA and CICS for OS/2 systems. 

Figure 43 illustrates the CICSOSLINK parameter format. Register 1 points to a 
list of pointers. The first is the address of the EIB, followed by the address of 
the COMMAREA, followed by the addresses of buffers of parameter data (one 
for each parameter). 



Register 1 ► Address of EIB 

Address of COMMAREA 
4 Byte Parm Pointer 

► 



High Order Byte, 

Bit 0 = 1 4 Byte Parm Pointer 



Figure 43. CICSOSLINK Parameter Format 

Parameter Passing in CICS for OS/2 Programs 

The diagrams shown in the previous sections are valid for CICS for OS/2 
programs, with the following differences: 

• The addresses pointed to by register 1 on MVS systems are placed as far 
pointers on the OS/2 stack in reverse order. 

• The high-order bit of the last parameter address is not set to 1. 
Parameter Passing in CICS for AIX Programs 

The diagrams shown in the previous sections apply to CICS for AIX programs 
with the following differences: 

• The addresses pointed to by register 1 on MVS systems are passed using a 
standard 32-bit C call to a DLL (OS/2) or a shared library entry point with 
the entry point name being equal to the DLL or shared library name. All 
parameters are passed by reference. 

• The high-order bit of the last parameter address is not set to 1. 
Calls from a Generated Program to a Program 

The CALL interface to a non-VisualAge Generator program is implemented 
the same as it is to a generated program. The NONCSP option on the 



1 to 30 parameter 
pointers 
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VisualAge Generator CALL has no effect on generation of the calling program, 
but it should be specified for documentation and environment portability 
considerations. If the non-Visual Age Generator program uses a linkage 
convention other than the defaults, the program must be specified in the 
linkage table with the correct values for linkage type and parameter format. 
See "Calls from a Generated Program to a Generated Program" on page 416 
for a description of the parameter formats used for calls. 

On MVS or VSE systems, CICSLINK linkage must be specified if the called 
program is written in a programming language other than COBOL or 
Assembler. 

The user program name must be defined to CICS and the program must exist 
in the operating system load library, or a NOT FOUND condition results. The 
program must also be link edited according to CICS command level 
programming rules. Refer to the CICS application programmer's reference for 
more details. 

Handling Abends on Calls from Generated Programs to Programs 

In CICS for MVS/ESA and CICS for VSE/ESA, there are abend handling 
considerations when a generated program uses a COBOL CALL instead of a 
CICS LINK to call a non- VisualAge Generator: COBOL program. In this 
situation, the COBOL run-time environment disables the CICS abend handling 
requested by the calling program on entry to the called program. The called 
program should reinstate the abend handler for the generated program by 
issuing a CICS POP HANDLE statement on entry to the called program and a 
CICS PUSH HANDLE statement on exit from the called program. 

If the abend handler is not reinstated and an abnormal termination occurs in 
the called program, normal error cleanup for the generated program is not 
performed. The shared table use count is not updated when the program ends 
unsuccessfully. This might lead to an unnecessary copy of a shared table 
remaining in storage. No VisualAge Generator Server for MVS, VSE, and VM 
error messages are issued by the abend handler. 

Refer to the application programming guide for your CICS for MVS/ESA or 
CICS for VSE/ESA system for more information on using COBOL calls in an 
CICS for MVS/ESA or CICS for VSE/ESA environment. 

Calls to non-CICS Programs on CICS for OS/2 

Calls to non-CICS programs require using DYNAMIC or STATIC linkage with 
the OSLINK parameter format. The called program must not issue any EXEC 
CICS commands. Parameters in OSLINK format are always passed by 
reference. A far pointer is placed in the stack in reverse order for each 
parameter. 
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Calls to non-CICS Programs on CICS for AIX 

Calls to non-CICS program require using DYNAMIC or STATIC linkage with 
the OSLINK parameter format. The called program must not issue any EXEC 
CICS commands. Parameters in OSLINK format are always passed by 
reference using a standard 32-bit C call to a DLL (OS/2) or shared library 
entry point with the entry point name being equal to the DLL or shared 
library name. 

Examples of COMMPTR Definitions in Programs 

When CICSLINK linkage and COMMPTR parameter format are used in calls 
in generated programs, pointers to the passed parameters are in the CICS 
COMMAREA. Figure 44 on page 422 and Figure 45 on page 423 show 
examples of how non-VisualAge Generator programs receive parameters that 
are passed in the CICS COMMAREA. Three parameters are passed in these 
examples (a record, a level-77 data item, and working storage). 
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Parameter Addressing Using Assembler Language CICSLINK with 
COMMPTR 



Parameter Addressing Using Assembler Language 





L 


PARMPTR.DFHEICAP 


Address parameter list 




USING 


PARMAREA , PARMPTR 






L 


PARM1PTR.PARM1A 


Address parameter 1 




USING 


PARM1 , PARM1PTR 






L 


PARM2PTR.PARM2A 


Address parameter 2 




USING 


PARM2.PARM2PTR 






L 


PARM3PTR.PARM3A 


Address parameter 3 




USING 


PARM3.PARM3PTR 






. 




And so on. 


PARMAREA 


■ 

DSECT 




Define storage layout of parmlist 


PARM1A 


DS 


F 


Passed pointer to parameter 1 


PARM2A 


DS 


F 


Passed pointer to parameter 2 


PARM3A 


DS 


F 


Passed pointer to parameter 3 


PARM1 


DSECT 




Define storage layout of passed parm 


RECORD 


EQU 




Parameter is a record 


FLD1 


DS 


L10 


Fields in record structure 


FLD2 


DS 


L2G 


ii ii 


FLD3 


DS 


L20G 


ii ii 








And so on. 


PARM2 


DSECT 




Define storage layout of passed parm 


L7791 


DS 


L5 


Parameter is single data item level-! 


PARM3 


DSECT 




Define storage layout of passed parm 


WORKSTOR 


EQU 




Parameter is working storage 


FLD5 


DS 


L5 


Fields in working storage 


FLD6 


DS 


L5 





And so on. 



Figure 44. Parameter Addressing Using Assembler Language CICSLINK with COMMPTR 
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Parameter Addressing Using COBOL CICSLINK with COMMPTR 



Parameter Addressing Using COBOL 



LINKAGE SECTION. 
01 DFHCOMMAREA. 
02 PARM1A 
02 PARM2A 
02 PARM3A 
01 PARM1. 
02 RECORD. 
03 FLD1 
03 FLD2 
03 FLD3 



USAGE IS POINTER. 
USAGE IS POINTER. 
USAGE IS POINTER. 



PIC X(10). 
PIC X(20). 
PIC X(200). 



And so on. 



01 PARM2. 

02 L7701 
01 PARM3. 
02 W0RKST0R. 
03 FLD5 
03 FLD6 



PIC X(5). 



PIC X(5). 
PIC X(5). 



PROCEDURE DIVISION. 

SET ADDRESS OF PARM1 TO PARM1A 

SET ADDRESS OF PARM2 TO PARM2A 

SET ADDRESS OF PARM3 TO PARM3A 



And so on. 



And so on. 



Figure 45. Parameter Addressing Using COBOL CICSLINK with COMMPTR 

From a Program to a Generated Program 

The program must be defined as a called program. The calling non-VisualAge 
Generator program is responsible for setting the parameters as specified in the 
linkage table for the called program when it was generated. See "Calls from a 
Generated Program to a Generated Program" on page 416 for diagrams of the 
linkage generated for different parameter formats as specified in the linkage 
table. 

The format of items in the parameter list must match the definition specified 
for the parameters received by the called program. If they are not the same 
the results are not predictable. 

The following example shows the format of CICS LINK for a program call to 
a program generated with the COMMPTR parameter format: 
EXEC CICS 

LINK PROGRM('MYAPPL') C0MMAREA(record of pointers) 
LENGTH (length of C0MMAREA) 
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For some types of linkage in the CICS environment, at exit the called 
programs set the COBOL special register RETURN- CODE to the value of the 
VisualAge Generator special function word EZERCODE.> The return code 
that is passed back can be tested by the calling non- VisualAge Generator 
programs. For information on the types of linkages, refer to EZERCODE in 
the VisualAge Generator help facility. 

Calls from non-CICS Programs to a Generated Program on OS/2 

All programs generated for OS/2 are CICS for OS/2 programs. However, the 
following types of non-CICS for OS/2 programs can call a generated program 
using the CICS for OS/2 External Call Interface: 

• Presentation Manager programs 

• Text-windowed programs 

• Dialog Manager programs 

• Full-screen programs 

OS/2 full-screen and text- window programs can call generated programs 
asynchronously and synchronously. Presentation Manager and Dialog 
Manager programs must call generated programs asynchronously. 

The called program must be generated with CICSLINK link type and 
COMMDATA parameter format receiving a single parameter. The parameter 
must be a record with a record definition that matches the structure of the 
information passed in the COMMAREA via the External Call Interface. For 
additional information on the CICS for OS/2 External Call Interface, refer to 
the CICS for OS/2 Application Programming Version 2 document. 

Note: The above restriction for CICSLINK and COMMDATA does not apply 
when you are testing the calling program under the VisualAge 
Generator test facility and the called program is already generated to 
run under CICS OS/2. In this situation, the test facility uses whatever 
linkage and parameter interface you have requested in the linkage 
table. 



Transfers in the CICS Environment 

Transfers in the CICS environment are supported in the following ways: 

• An XFER statement without map is implemented as a CICS START 
command if the /NOGENRET generation option is specified; or as a CICS 
RETURN IMMEDIATE command if the /GENRET generation option is 
specified. /GENRET is supported only for CICS for MVS/ESA systems. 

• An XFER statement with a map is implemented as a CICS RETURN 
TRANSID command. 

• A DXFR statement is implemented as a CICS XCTL command. 
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From a Generated Program to a Generated Program Using an XFER 
Statement 

An XFER can specify two optional parameters: a map name that is the First 
Map of the transferred-to program and a record. The XFER causes a new 
CICS transaction to be invoked. Recoverable resources are committed as part 
of the XFER process. If a map is specified on the XFER statement, the 
scheduling of the new transaction is deferred until the program user 
responds. Otherwise, the new transaction is scheduled as soon as the first 
transaction ends. 

XFER without a Map 

If the /NOGENRET generation option is used and you do not specify a map 
on the XFER statement, the originating program issues an EXEC CICS START 
command for the target transaction. If a record is specified on the XFER 
statement, the record is passed as FROM data on the EXEC CICS START 
command; otherwise, the FROM and LENGTH parameters are not used. 

The following example shows the format of the START for a record: 

EXEC CICS START TRANSID( 'transid' ) FROM(record) 

LENGTH (LENGTH OF record) 
TERMID(current terminal) 

The terminal is always included in the TERMID of the CICS START command 
if the XFER is issued from a main transaction. The transaction is not invoked 
unless the terminal is in TRANSCEIVE status in the CICS TCT 

Note: A START command refers to a CICS transaction ID that is 4 characters 
or less. CICS starts the new CICS transaction on the same terminal if 
the terminal is not currently in TRANSACTION status. 

The started transaction can start a non-VisualAge Generator program or a 
generated program defined as a main transaction. After starting the new 
transaction, the program issuing an XFER statement ends. 

If the / GENRET generation option is used and you do not specify a map on 
the XFER statement, the originating program issues an EXEC CICS RETURN 
IMMEDIATE command for the target program. If a record is specified, the 
record is passed in the 11th through n bytes of the COMMAREA. The first 10 
bytes are binary zeros indicating that this is an XFER statement passing a 
record. 

EXEC CICS START TRANSID( 'transid' ) FROM(record) 

LENGTH (LENGTH OF record) 
TERMID(current terminal) 
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XFER with a Map 

If you specify a map name on the XFER, the originating program displays the 
map and returns to CICS. The EXEC CICS RETURN command specifies the 
transaction ID coded on the XFER statement as the next transaction to be 
scheduled when the program user responds to the screen. The target 
transaction must be associated with a VisualAge Generator program. The 
target program must have a First Map specified, and this First Map must be 
identical to the map specified on the XFER. 

If a record is specified on the XFER statement, the record is received in the 
COMMAREA by the target program. 

From a Generated Program to a Program Using XFER 

A transfer using an XFER statement from a VisualAge Generator program to a 
non- VisualAge Generator transaction is implemented differently depending on 
whether or not the /GENRET generation option is specified. The NONCSP 
parameter can be coded on the XFER for documentation purposes. XFER with 
a map is not supported. Because XFER starts a new CICS transaction, a CICS 
SYNCPOINT occurs as a result of an XFER statement. 

If the /NOGENRET generation option is specified, the XFER statement is 
implemented as an EXEC CICS START command. The record passed when 
using an XFER statement is put into CICS temporary storage. A program must 
retrieve it into its own data area. CICS also passes the length of the retrieved 
data to the program. This length is zero if no record is passed. The following 
CICS command retrieves the passed record: 

EXEC CICS RETRIEVE INTO(my-worki ng-storage-area) LENGTH (work-length) 

Note: Be sure to put the length of my-working-storage-area into work-length 
before the RETRIEVE command. 

If the / GENRET generation option is specified, then the XFER statement is 
implemented as an EXEC CICS RETURN IMMEDIATE. The first 10 bytes of 
the COMMAREA received by the trans ferred-to program is binary zeros. If a 
record is specified on the XFER statement, the record is found in the 
COMMAREA starting at the 11th byte. 

From a Program to a Generated Program Using CICS START Command 

The program can issue a CICS START command for the CICS transaction ID 
associated with the generated program. The terminal must be specified in the 
TERMID of the CICS START command if a main transaction program is being 
started. The transaction is not invoked unless the terminal is in TRANSCEIVE 
status in the CICS TCT A record can be passed in the FROM area of the 
START command. If a record is passed, it is used to initialize the primary 
working storage record for the generated program. Transferring with a map is 
not supported, but the transferred-to program can have a First Map 
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automatically be displayed. The example below shows the format of the 
START command that can be used when passing a record to the generated 
program: 

EXEC CICS START TRAMSID( 'transid' ) FROM(record) 

LENGTH (LENGTH OF record) 
TERMID(current terminal) 

Note: If the transferring program uses the EXEC CICS START command, you 
can specify either the /GENRET or the /NOGENRET generation option 
when you generate the transferred-to program. 

From a Program to a Generated Program Using CICS RETURN 
IMMEDIATE 

If the program was generated with the / GENRET generation option, the 
program can issue a CICS RETURN IMMEDIATE command for the CICS 
transaction. A record can be passed in the COMMAREA and must start in the 
11th byte. The first 10 bytes must be binary zeros. If a record is passed, it is 
used to initialize the primary working storage record for the generated 
program. Transferring with a map is not supported, but the transferred-to 
program can have a First Map that is automatically displayed. 

The example below shows the format of the RETURN IMMEDIATE for a 
record: 

EXEC CICS RETURN TRANSID( 1 transi d 1 ) 

COMMAREA (1G bytes of low-values + record) 
LENGTH(10 + length of record) 
IMMEDIATE 

Note: When you use EXEC CICS RETURN IMMEDIATE to transfer, specify 
the /GENRET option when generating the program to be started. 

From a Generated Program to a Generated Program Using a DXFR 
Statement 

The generated program immediately transfers control to the transferred-to 
program using a CICS XCTL command. A record, if specified, is passed in the 
COMMAREA. A CICS SYNCPOINT occurs on a DXFR statement if the 
following occurs: 

• /SYNCDXFR is specified and a PSB scheduled. 

• /NOSYNCDXFR is specified for the transferring program and the 
transferring program had scheduled a PSB and different PSB names were 
identified during program specification for the two programs. 

Otherwise, no SYNCPOINT occurs. The following example shows the 
command to transfer program control: 

EXEC CICS XCTL('applnam') COMMAREA(record) 

LENGTH(length of record) 
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From a Generated Program to a Program Using DXFR 

The generated program immediately transfers control to the transferred-to 
program by issuing a CICS XCTL to the program name specified on the DXFR 
statement. A record, if specified, is passed in the COMMAREA. A CICS 
SYNCPOINT occurs on a DXFR statement if a PSB is scheduled. 

A DXFR from a VisualAge Generator generated program to a non-VisualAge 
Generator program is implemented as it is for a transfer from a generated 
program to a generated program. The NONCSP parameter is required on the 
DXFR or on the DXFRLINK tag defined for the DXFR in the linkage table. 
NONCSP indicates that all resources allocated by VisualAge Generator Server 
or VisualAge Generator Server for MVS, VSE, and VM are released. The 
non- VisualAge Generator program receives data in the COMMAREA. 

From a Program to a Generated Program Using CICS XCTL 

The program issues a CICS XCTL command to transfer to the generated 
program. A record can be passed. 

The program must be defined as a main program, and the program name is 
the only required parameter. It must be pointing to a valid VisualAge 
Generator program name. 

EXEC CICS XCTL ('applnam') COMMAREA(record) 

LENGTH (length of record) 

If the target program runs as segmented, be sure that before the target 
program does a CONVERSE it sets EZESEGTR to a transaction code 
associated with the target program in the PCT Otherwise, when the input 
from the terminal is received, the default value in EZESEGTR (the current 
transaction code) causes the program to be restarted instead of the target 
program. 

You can set EZESEGTR to the proper transaction code by doing one of the 
following: 

• Specifying the transaction code as the restart parameter for the /TRANSID 
generation option. 

• Moving the transaction code to EZESEGTR within the program before the 
first CONVERSE. 

Start Asynchronous Tasks from a Program 

An asynchronous task is started by a program with a CALL CREATX 
statement that issues a CICS START command, or by a non- VisualAge 
Generator program with a CICS START command. The following example 
shows the CICS START command that is used for an asynchronous task: 

EXEC CICS START ('transid') FROM (WORK) LENGTH(length of WORK) 
TERMID(dest-termid) 
RTERMID(async-print-dest) 
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The meanings of RTERMID and TERMID when starting asynchronous tasks 
are described in the following paragraphs. 

RTERMID is optional, based on the value of TERMID. It is only used if the 
value specified with TERMID is 4 bytes of binary zeros. 

If you want to start an asynchronous task without an associated CICS 
terminal ID, then omit the TERMID keyword from the START command. The 
value in RTERMID should be the print destination for the started batch 
program. The RTERMID value is used to initialize EZEDESTP in the started 
program if you specify /PRINTDEST=TERMID during generation of this 
started program. EZEDESTP is the print destination special function word. 

If you want to start a task with an associated terminal ID, then the value 
specified in TERMID should be a valid CICS terminal ID. The results are not 
predictable if you specify the terminal ID associated with the current 
transaction. Use the XFER, statement to end the current transaction and start a 
new transaction at the current terminal. If TERMID is specified on the START 
command, RTERMID is an optional parameter. If it is passed, it must specify 4 
bytes of binary zeros. 

Receiving Data in a Started Task 

Programs started with a CALL CREATX function must always use the 
RTERMID parameter on the CICS RETRIEVE issued to retrieve passed 
working storage, even though the value might be all zeros. 

An asynchronous task that is started by a program with a CALL CREATX can 
receive the data that was passed by doing the following: 

EXEC RETRIEVE INTO (my-worki ng-storage-area) LENGTH (work-length) 
RTERMID (user-rtermid) 

Note: Be sure to put the length of my-working-storage-area into work-length. 
Programs started using CALL CREATX must always include the 
RTERMID on the CICS RETRIEVE statement issued to retrieve passed 
working storage. If RTERMID contains 4 bytes of binary zeros, it 
should be ignored. If RTERMID is not 4 bytes of binary zeros, it 
contains the printer (prid) specified for the CALL CREATX statement. 



Appendix F. Transferring Control in the CICS Environment 429 



430 VisualAge Generator: User's Guide 



Appendix G. Transferring control in C++ OS/2, 
Windows NT, AIX, and HP-UX programs 



In C++ programs generated for the OS/2, Windows NT, AIX, and HP-UX 
environments you can transfer control using the CALL, DXFR, and XFER 
statements. 



Calls from a generated program to a generated program 

The called program runs and returns control to the calling program when the 
program ends or an EZECLOS is issued. No commit occurs on the return 
from the called program. 

Up to 30 parameters can be passed on the call. The call is a standard C call to 
a DLL (OS/2 and Windows NT) or shared library (AIX and HP-UX) entry 
point. All parameters are passed by reference. 

No linkage table entry is required. The default CALLLINK attributes for this 
type of call are LINKTYPE=DYNAMIC and PARMFORM=OSLINK. 



Calls from a program to a generated program 

The program must be defined as a called batch program. The called program 
runs and returns control to the calling program when the program ends or an 
EZECLOS is issued. No commit occurs on the return from the called program. 

Up to 30 parameters can be passed on the call. The call is a standard 32-bit C 
call to a DLL (OS/2 and Windows NT) or shared library (AIX and HP-UX) 
entry point with the entry point name being equal to the DLL or shared 
library name. All parameters are passed by reference. The parameter 
declaration in the calling program must match the definition of the 
parameters to the program. 

No linkage table entry is required. The default CALLLINK attributes for this 
type of call are LINKTYPE=DYNAMIC and PARMFORM=OSLINK. 
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Calls from a generated program to a program 

The called program must be an entry point in a DLL (OS/2 and 
Windows NT) or shared library (AIX and HP-UX). The program must return 
to the calling program when complete. The program should not commit or 
rollback recoverable resources if the called program accesses relational 
databases. 

Up to 30 parameters can be passed on the call. The call is a standard 32-bit C 
call to a DLL (OS/2 and Windows NT) or shared library (AIX and HP-UX) 
entry point. All parameters are passed by reference. The parameter declaration 
in the program must match the definition of the parameters to the program. 

If the DLL or shared library name is different from the entry-point name, 
specify the library name in the linkage table using the DLLNAME attribute. If 
the entry-point name is longer than eight characters, use an alias for the 
program name on the CALL statement, and specify the alias name as the 
APPLNAME attribute and the entry point name as the EXTERNALNAME 
attribute in the linkage table entry. The other CALLLINK attributes for this 
type of call are LINKTYPE=DYNAMIC and PARMFORM=OSLINK. 



Transfer from a generated program to a generated program 

A main program implements XFER/DXFR to another main program via a 
standard OS/2 or Windows NT DLL call. XFER commits recoverable 
resources across the call, DXFR does not. Local (process) memory is used to 
transfer the XFER/DXFR record. XFER with a map is supported. 

No linkage table entries are required when generating this type of transfer. 



Transfer from a generated program to a program 

A main program implements XFER/DXFR to a program using an OS/2 
DosStartSession or AIX and HP-UX fork system call. The program must have 
a file type of EXE. XFER/DXFR with a record are supported; XFER with map 
is not. 

The XFER/DXFR record is passed in named shared memory with the name 
\SHAREMEM\FCWpppp (OS/2), SHAREMEMFCWpppp (Windows NT), or 
/ tmp / fcwipcpppp (AIX and HP-UX) where pppp is the sender's process id. 
The parameter block in the shared memory buffer has the following structure: 

{ 

unsigned long Length; //Length of XFER/DXFR 

unsigned char Data[l]; //XFER/DXFR record data 
} 
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To synchronize the sending and receiving of the parameter block between 
programs, a named shared semaphore is used. The semaphore name is 
\SEM32\FCWpppp (OS/2), SEM32FCWpppp (Windows NT), or 
/ tmp /f cwipcpppp (AIX and HP-UX) where pppp is the sender's process id. 
The sender's process id is made available to the program via the environment 
variable FCWPPID. 

In order to transfer, the program constructs the parameter block, writes the 
FCWPPID environment variable, starts the receiver process, and waits for the 
semaphore to be posted. The program must read the transfer record and post 
the semaphore. When posted, the program deletes the shared memory and 
ends. 

In order for program to transfer with this protocol, the XFER or DXFR 
statement must be coded with the NONCSP option. 



Transfer from a program to a generated program 

A program can start or transfer to a generated program using a OS/2 
DosStartSession or AIX and HP-UX fork system call. The program must start 
the stub FCWRUN.EXE passing the program name as a command line 
parameter. 

A record can be passed to the program in named shared memory with the 
name \SHAREMEM\FCWpppp (OS/2) or / tmp /f cwipcpppp (AIX and 
HP-UX) where pppp is the sender's process id. The parameter block in the 
shared memory buffer has the following structure: 

{ 

unsigned long Length; //Length of record 
unsigned char Data[l]; //record data 

} 

In order to synchronize the sending and receiving of the parameter block 
between programs, a named shared semaphore is used. The semaphore name 
is \SEM32\FCWpppp (OS/2) or / tmp /f cwipcpppp (AIX and HP-UX) where 
pppp is the sender's process id. The sender's process id is made available to 
the program via the environment variable FCWPPID. 

In order to transfer, the sender must construct the parameter block, write the 
FCWPPID environment variable, start the receiver process, and wait for the 
semaphore to be posted. The receiver stub reads the transfer record and post 
the semaphore. When posted, the sender deletes the shared memory and 
ends. 

No linkage table entry is required for use of this transfer protocol. 
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Starting an asynchronous process from a generated program 

To start an asynchronous process running a C++ main batch program on 
OS/2, Windows NT, AIX, or HP-UX, call the CREATX service, omitting the 
prid and recip parameters. The CREATX record data area is passed to the 
started program. If a program is started, the data is used to initialize the 
working storage record of the program. 

The process is started using an OS/2 DosStartSession, Windows NT Create 
Process, or AIX and HP-UX fork system call. The record data is passed in 
named shared memory using the same algorithm that is used for transferring 
between generated programs to programs. 



Starting an OS/2 or Windows NT GUI client program from a generated program 

To start an OS/2 GUI client program from a generated program, have the 
program call a non- Visual Age Generator C DLL as follows: 
CALL STRTGUI GUINAME 

where GUINAME is an 8-byte CHA item containing the name of the GUI 
program to be started. No data is passed to the GUI. 

Following is the STRTGUI.C function: 

finclude <process.h> 
finclude <string.h> 

int _System STRTGUI (char * guiname) 

{ 

char gui name_stri ng [9] ; 

strncpy (gui name_stri ng, gui name, 8) ; 
guiname_string[8] = NULL ; 

int rc = _spawnlp( P_N0WAIT, 
"cmd.exe ", 
"cmd.exe ", 
"eze2run open ", 
guiname_stnng, 
NULL ); 

return ( rc ) ; 

} 
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Appendix H. Transferring control in GUI programs 



GUI programs can call generated programs or other programs. In a GUI 
program, a call can be defined by coding a CALL statement or by drawing an 
event-action connection from an event to the execute action of a callable 
function object that represents the called (target) program. 



Calls from a GUI client program to a generated C++ program 

The called program runs and returns control to the calling program when the 
program ends and an EZECLOS is issued. No commit occurs on the return 
from the called program. 

Up to 30 parameters can be passed on the call. The call is a standard 32-bit C 
call to a DLL. All parameters are passed by reference. 

A linkage table entry is required. The CALLLINK attributes are 
LINKTYPE=DYNAMIC and PARMFORM=OSLINK. 



Calls from a GUI client program to a program 

The called program must be an entry point in a DLL or an executable 
program (EXE or CMD file). 

No linkage table is required for calling an executable. Up to 30 parameters can 
be passed to the executable on the call. The parameters are placed in the 
command line separated by blanks. The parameters are passed by value. 
Parameter modifications by the called program are not passed back to the 
calling program. 

Specify a linkage table entry if the called program is an entry point in a DLL. 
Up to 30 parameters can be passed on the call. The call is a standard C call to 
a DLL. All parameters are passed by reference. The parameter declaration in 
the program must match the definition of the parameters to the program. 

If the DLL name is different from the entry-point name, specify the library 
name in the linkage table using the DLLNAME attribute. If the entry-point 
name is longer than eight characters, use an alias for the program name on 
the CALL statement, and specify the alias name as the APPLNAME attribute 
and the entry-point name as the EXTERNALNAME attribute in the linkage 
table entry. If the DLL is a 16-bit program, specify BITMODE=16. The other 
CALLLINK attributes for this type of call are LINKTYPE=DYNAMIC and 
PARMFORM=OSLINK. 
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Appendix I. Transferring Control in the Non-CICS Host 
Environments 



In non-CICS environments, you can transfer program control using CALL, 
XFER, and DXFR statements. 



Calls in the MVS/TSO, MVS Batch, IMS BMP, IMS MPP, VM CMS, VM batch, and 
VSE Batch Environments 

In non-CICS environments, standard OS linkage conventions are used. Up to 
30 parameters can be passed on the call. The called program runs and returns 
to the calling program when the program ends. 

You use the generation linkage table to specify the type of linkage generated 
for a CALL statement. For non-CICS environments, you can specify that the 
CALL be generated either as a DYNAMIC or a STATIC COBOL call with 
parameters passed using a standard COBOL parameter list (OSLINK), with all 
parameters passed by reference. 

Calls from a Generated Program to a Generated Program 

CALL statements are generated as standard COBOL CALLs. The parameters 
on the CALL statement are the parameters on the COBOL CALL. All 
parameters are passed by reference, not by content. You use the linkage table 
to specify whether the COBOL CALL is a dynamic or static call. 

The compiled COBOL CALL passes parameters using standard linkage 
conventions. Register 1 points to a list of parameter addresses. The high order 
byte of the last parameter address is set to 1. 



Register 1 



High Order Byte, ► 

Bit 0 = 1 



4 Byte Parm Pointer 



4 Byte Parm Pointer 



1 to 30 parameter 
pointers 



Figure 46. How Parameters Are Passed in COBOL CALL Statements 

Calls from a Generated Program to a Program 

The call to the program is generated the same as a call to a generated 
program. Calls to programs written in PL/I must be done as static calls. If the 
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program is not written in COBOL, the rules for interfacing to other languages 
described in the application programming guide for your release of COBOL 
must be followed. 

Calls from a Program to a Generated Program 

The program uses a standard COBOL CALL statement to call the generated 
program. All parameters are passed by reference, not by content. Calls from 
programs written in PL /I must be done as static calls. If the program is not 
written in COBOL, the rules for interfacing to other languages described in 
the application programming guide for your release of COBOL must be 
followed. 



Transfers in the MVS/TSO, MVS Batch, IMS BMP, VM CMS, VM batch, and VSE 
Batch Environments 

XFER and DXFR statements are supported in the MVS/TSO, MVS batch, and 
IMS BMP environments in one of the following ways: 

Generated program to a generated program 

Either XFER or DXFR statements can be used. An XFER statement is 
generated as an OS XCTL macro. A DXFR statement can be 
implemented as either a static or dynamic call. 

Generated program to a program 

Either XFER or DXFR statements can be used. Both are generated 
using the OS XCTL macro. NONCSP must be specified for a DXFR, 
either as an option on the statement or as an entry on the DXFRLINK 
tag in the linkage table. 

Program to a generated program 

The program must use the OS XCTL macro. 

In the VSE batch environment, program to program DXFR is the only transfer 
supported. The DXFR is implemented as either a static or dynamic call. 

From Generated Program to Generated Program Using DXFR 

A generated program transferring with a DXFR statement to another 
generated program is implemented by issuing a COBOL CALL to the target 
program. If that program, in turn, transfers using a DXFR statement, it returns 
to the first program to perform the transfer. This method of transferring 
program control to generated programs using COBOL CALLs from the initial 
program permits the run-time environment to be maintained across the 
transfer. 

From Generated Program to Generated Programs Using XFER 

The generated program ends and returns to a VisualAge Generator Server for 
MVS, VSE, and VM stub program linked with the generated program. The 
stub issues an OS XCTL macro to transfer to the target program. Both 
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VisualAge Generator Server for MVS, VSE, and VM and COBOL cleanup and 
reestablish the run-time environment each time an OS XCTL macro is used. 
Both VisualAge Generator Server for MVS, VSE, and VM and COBOL use 
termination and initialization logic for the OS XCTL. You can use the 
/SYNCXFER generation option to control commit points. 

From a Program to a Generated Program Using XCTL 

Transfers from a non- VisualAge Generator program to a generated program in 
the MVS/TSO, MVS batch, and IMS BMP environments can be implemented 
using an OS XCTL to the generated program. Two ways of passing 
parameters on the XCTL are described in the following sections. 

Standard Linkage Conventions 

One or two parameters are passed to the receiving program on the XCTL. The 
first parameter is the working storage buffer consisting of a 2-byte binary 
length field containing the buffer length (working storage data length plus 
10), an 8-byte filler field, and the working storage data. The second parameter, 
used only if the generated program is a DL/I program, is the EZEDLPSB 
special function word. Figure 47 shows the format of the parameter list that 
the transferring program should pass. See "EZEDLPSB Parameter Format for 
PSB Information" on page 441 for the format of the EZEDLPSB special 
function word. Register 1 can be set to 0 if there is nothing to pass. 



Register 1 



High order byte 
must have 
bit 0 = 1 



Pointer to 
Working Storage 



Pointer to 
EZEDLPSB 



Length (2 bytes) 



Filler (8 bytes) 



Working Storage Data 



EZEDLPSB 



Figure 47. Passing Parameters on XCTL — Example 1 

If you want VisualAge Generator Server for MVS, VSE, and VM to issue a 
FREEMAIN for the areas passed to the generated program, obtain a single 
area for all passed data with a length equal to the length of the working 
storage data you want to pass plus 110 bytes (see Figure 48 on page 440). Set 
up the parameter list pointers at the top of the area, put the length and filler 
fields starting at offset 100 in the area, and move the working storage data to 
be passed into the area at offset 110. Issue the OS XCTL macro with register 1 
pointing to the start of the area. 
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004 



-008 



016 



-020 



026 



-►100 
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110 



Pointer to working storage 



Pointer to EZEDLPSB 



PSB name 



Simulated UIB pointer 



Simulated UIB 



Reserved for Host Services 



Length of working storage 



Reserved for Host Services 



Working storage data 



PCB 

Address 

List 



Figure 48. Passing Parameters on XCTL — Example 2 

Note: The high-order bit must be set on for either: 

• The pointer to working storage if EZEDLPSB is not passed 

• The pointer to EZEDLPSB if EZEDLPSB is passed. 



PCB List Linkage 

If the generated program is a DL/I program, the non- Visual Age Generator 
program can also transfer to the generated program, passing a list of PCBs as 
parameters on the XCTL. The generated program receives control in this way 
if it is started as a DL/I MVS batch job. The PCBs must map to the PSB 
definition expected by the generated program. 

The working storage record is initialized according to data type if the 
generated program is started with this interface. 

From a Generated Program to a Program Using DXFR or XFER 

The generated program ends and returns to a VisualAge Generator Server for 
MVS, VSE, and VM stub program linked with the generated program. The 
stub issues an OS XCTL macro to transfer to the program. If the program was 
started with a PSB, both the working storage record and the EZEDLPSB 
structure are passed as XCTL parameters. Otherwise, only the working storage 
record is passed. Register 1 is 0 if no parameters are passed. See Figure 49 on 
page 441. 
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The receiving program can issue a FREEMAIN for the parameters passed 
from the generated program. The FREEMAIN address is the address in 
register 1. The FREEMAIN length is the value in the length field plus 100. 

If DXFR is used, the NONCSP option must be specified on the DXFR 
statement or the DXFRLINK tag for the DXFR in the linkage table. 

XFER with a map is not supported. 



Register 1 



High order byte 
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Pointer to 
Working Storage 



Pointer to 
EZEDLPSB 



Length (2 bytes) 



Filler (8 bytes) 



Working Storage Data 



EZEDLPSB 



Figure 49. Parameter List to VisualAge Generator Program from Transferring Non-VisualAge 
Generator Program 

EZEDLPSB Parameter Format for PSB Information 

Generated COBOL programs use the EZEDLPSB special function word for 
passing PSB information between programs. Refer to the online help system 
for additional information about the EZEDLPSB special function word. The 
EZEDLPSB special function word is a 12-byte field consisting of an 8-byte PSB 
name followed by a 4-byte address. The address points to a simulated CICS 
user interface block (UIB). The simulated UIB is 6 bytes long. The first 4 bytes 
contain the address of the PCB address list for the PSB. The last 2 bytes must 
contain binary zeros. The PCB address list must be the list pointed to by 
register 1 when IMS or the DL/I region controller called the first program in 
the DL/I program set. Figure 50 on page 442 shows the format of the 
EZEDLPSB special function word. 
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Figure 50. Format of EZEDLPSB Special Function Word 



Transfers in the IMS MPP Environment 

Different considerations apply for transferring when IMSADF II programs are 
involved. See "Interfacing with IMSADF II Programs" on page 466 for 
additional information. 

VisualAge Generator programs that are defined as main transactions and 
generated for the IMS/VS target environment run as IMS message processing 
programs (MPPs). 

Transferring program control with an XFER is not supported for IMS/VS 
main batch programs. A non- Visual Age Generator program can invoke 
VisualAge Generator MPP programs using an IMS program-to-program 
message switch. The types of message switches are supported as follows: 

• Immediate message switch. Program A passes control directly to another 
transaction, that is associated with program B, without first responding to 
the originating terminal. For a conversational MPP, the program does this 
by inserting the scratchpad area (SPA) using an alternate PCB that has its 
destination set to the new transaction name. For a nonconversational MPP, 
the program inserts a message using an alternate PCB that has its 
destination set to the new transaction name. 

• Deferred message switch. Program A responds to the terminal and informs 
IMS to start another transaction, that is associated with program B, on the 
next input from the terminal. For a conversational MPP, the message switch 
is achieved by modifying the SPA to specify the new transaction name 
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before sending it back to IMS (using the I/O PCB). For a nonconversational 
MPP, the message switch is achieved by including the next transaction 
name on the map in such a way that it becomes the first 8 bytes of the 
input message. 

• Transferring from conversational to nonconversational or from 
nonconversational to conversational is not supported for generated 
programs. 

The definition and generation options of the transferred-to non-VisualAge 
Generator program or VisualAge Generator program control the type of 
switch that is possible and the way the data is passed. 

If the transferred-to transaction is a VisualAge Generator program, the First 
Map option determines the type of switch: 

• If First Map is not specified, an immediate program-to-program message 
switch is required. 

• If First Map is specified, either a deferred program-to-program message 
switch or an immediate program-to-program message switch can be used. If 
the immediate switch is used, the First Map is automatically displayed by 
the transferred-to program. However, this is less efficient than a deferred 
switch because the transferred-to program must be processed twice — once 
to display the First Map and once to read the data entered by the program 
user. 

If a non- VisualAge Generator program does a deferred program-to-program 
message switch to a VisualAge Generator program, the non- VisualAge 
Generator program should set the modified attribute on for all fields on the 
map and should set all other field attributes to the values that were defined 
during map definition. If the program user requests help or if edit errors 
occur, the program displays default data in any fields that did not have the 
modify attribute set and were not modified by the program user. The program 
uses the defined attributes for all other field attributes. 

If the transferred-to transaction is a non- VisualAge Generator program that 
needs map input from the message queue at the start of processing, the 
program should use a deferred program-to-program message switch. 
Otherwise, the program should use an immediate program-to-program 
message switch. 

The way data is passed is controlled by both the switch type and the 
execution mode. Table 22 on page 444 shows the methods used to pass data 
for both types of message switches. 
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Table 22. Program Switching in VisualAge Generator Programs (non-IMSADF Interface) 



Generation Option of 
Transferred-to Program 

Segmented conversational 
(non-ADF scratchpad area 
generation option — 
/SPA=n or 

/SPA=n„position where n 
is greater than 0 and 
position is either 15 or is 
equal to n. Position 
specifies the location of the 
segmentation status byte) 



Immediate Switch 
(Optional First Map) 

Define both programs as 
segmented. Generate both 
programs as conversational. 
The transferring program 
cannot send a map. If it is a 
VisualAge Generator 
program, it does this using 
an XFER with only a 
record. 



The transferred-to program 
can optionally have a First 
Map. 



Deferred Switch (with 
First Map) 

Define both programs as 
segmented. Generate both 
programs as conversational. 
The transferring program 
must write the map to a 
message queue associated 
with the terminal after first 
writing the SPA. If it is a 
VisualAge Generator 
program, it does this using 
an XFER with a map and 
an optional record. 

The transferred-to program 
must have a First Map. 



The record is transferred in The record, if any, is 
the SPA. transferred in the SPA. 



Segmented 

nonconversational and 
single segment 
(non-scratchpad area 
generation option / SPA=0) 



If position was specified, 
the segmentation status 
byte is always placed in the 
last byte of the SPA. The 
transferred-to program 
always ignores the value of 
the segmentation status 
byte. 



Define both programs as 
segmented, both as single 
segmented, or one program 
segmented and one 
single-segment. Generate 
both programs as 
nonconversational. 



If position was specified, 
the segmentation status 
byte is placed in either 
position 15 or the last byte 
of the SPA, based on the 
value of position. The 
transferred-to program uses 
the value of the 
segmentation status byte 
when there is an input map 
integrity problem caused by 
the program user pressing 
PA1 or PA2. 

Define both programs as 
segmented, both as single 
segmented, or one program 
segmented and one 
single-segment. Generate 
both programs as 
nonconversational. 
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Table 22. Program Switching in VisualAge Generator Programs (non-IMSADF 



Interface) (continued) 


Generation Option of 
Transferred-to Program 


Immediate Switch 
(Optional First Map) 


Deferred Switch (with 
First Map) 




The transferring program 
cannot send a map. If it is a 
VisualAge Generator 
program, it uses an XFER 
with only a record. 


The transferring program 
must write the map to a 
message queue associated 
with the terminal. If it is a 
VisualAge Generator 
program, it uses an XFER 
with a map and an optional 
record. 




The transferred-to program 
can optionally have a First 
Map. 


The transferred-to program 
must have a First Map. 




The record is transferred in 
the message. 


The record, if any, is 
transferred in the work 
database. 



Note: The segmentation status byte specified by position is used only for 
program-to-program transfers for conversational programs. The byte is present for 
transfers between conversational programs and other programs. However, a 
transferring non- VisualAge Generator program should always set the byte to blank. A 
transferred-to non- VisualAge Generator program should always ignore the value of the 
segmentation status byte. 



Note: The sample record layouts and definitions in the sections that follow 
are based on the COBOL conventions. PL/I requires a 4-byte length 
field rather than the 2-byte length field used for COBOL. Refer to the 
IMS/VS documentation for your system for additional information. The 
specific field names in the tables and figures are used for illustrative 
purposes only; the actual field names might vary in the generated code. 

Transferring with Segmented Conversational Programs 

Depending on the type of XFER statement used, the following can be passed 
between two programs: 

• Scratchpad area (SPA). 

• MFS map. See the "VisualAge Generator Main Transaction MFS MID 
Format" on page 448 section for more information. 
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Segmented Conversational Transaction SPA 

Table 23 describes the format of the IMS scratchpad area: 



Table 23. Format of IMS Scratchpad Area 



Field 


Length in Bytes 


Type of Data 


Description 


SPA length 


2 


Binary 


The length of the 
segment. 


SPA ID 


4 


Binary 


A unique name 
used to identify the 

fl r~\ A . -w-\ rs~< mi - 

SPA to IMS. This 
name must not be 
changed by the 
MPP 


IMS transaction 
name 


8 


Character 


The IMS transaction 
name for the 
VisualAge Generator 
program. 


Segmentation Status 
Byte (Optional) 


1 


Hexadecimal 


This optional byte is 
present if 



/SPA=n„15 was 
specified and this is 
a deferred switch. It 
indicates whether 
data was saved in 
the work database. 



Program working Variable Variable This area contains 

storage the working storage 

record used by the 
transferred-to 
program. 
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Table 23. Format of IMS Scratchpad Area (continued) 



Field Length in Bytes Type of Data Description 

Segmentation Status 1 Hexadecimal This optional byte is 

Byte (Optional) present if 

/SPA=n„15 or 
/ SPA=n„n was 
specified and this is 
an immediate 
switch. In this case 
the contents of the 
byte are ignored. 
This optional byte is 
also present if 
/SPA=n„n was 
specified and this is 
a deferred switch. In 
this case, it indicates 
whether data was 
saved in the work 
database. 



Figure 51 shows the segment's COBOL definition for a scratchpad area passed 
in either a deferred or an immediate program-to-program message switch for 
conversational processing. 

* SPA 10 area. 
01 SPA. 

G5 SPA-LENGTH PIC S9(4) COMP. 

G5 SPA-ID PIC S9(9) COMP. 

05 IMS-IRAN-NAME PIC X(8). 

05 CSP-OPIIONAL-SSM-BYIE PIC X(l). Q 
05 CSP-APPL-WS-DAIA. 

10 data-item-1 PIC 

10 data-item-2 PIC 

05 SPA-ID PIC S9(9) COMP. 

05 IMS-IRAN-NAME PIC X(8). 



05 CSP-0PTI0NAL-SSM-BYTE PIC X(l). Q 

Figure 51. COBOL Declare for Scratchpad Used with Message Switch 

Notes on Figure 51 are as follows: 

Number 

Explanation or Comment 
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Q This optional byte is present if /SPA=n„15 was specified and this is a 
deferred switch. It indicates whether data was saved in the work 
database. 

Q This optional byte is present if /SPA=n„15 or /SPA=n„n was specified 
and this is an immediate switch. In this case the contents of the byte 
is ignored. This optional byte is also present if /SPA=n„n was 
specified and this is a deferred switch. In this case, it indicates 
whether data was saved in the work database. 

The data identified as "Program working storage" in Table 23 on page 446 is 
treated as the primary working storage record for the transferred-to program. 
This technique enables a non-VisualAge Generator program to store data in 
the SPA and switch to a VisualAge Generator program (or a series of 
VisualAge Generator programs) that use or modify the SPA data. The 
VisualAge Generator program can eventually switch back to a non- VisualAge 
Generator program with information from the VisualAge Generator program 
contained in the SPA. Follow the IMS restrictions regarding changes in the 
SPA size. 

VisualAge Generator Main Transaction MFS MID Format 

The MFS message input descriptor (MID) and message output descriptor 
(MOD) that are used to read and write maps to terminals for a deferred 
program-to-program message switch share the same basic format. Table 24 
shows the record layout for a MID. For an MFS MOD, the IMS transaction 
name and the value of the COND parameter (map name) are reversed. In 
addition, some fields in the MOD are ignored. 

Table 24. Record Layout for MFS Message Input Descriptor (MID) 



Field 


Length in Bytes 


Type of Data 


Description 


Segment length 


2 


Binary 


The length of the 
segment 


Reserved 


2 


Binary 


Reserved for IMS 


IMS transaction 
name 


8 


Character 


The IMS transaction 
name for the 
VisualAge Generator 
program 


Reserved 


1 


Character 


Reserved for 
VisualAge Generator 
Server for MVS, 
VSE, and VM 
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Table 24. Record Layout for MFS Message Input Descriptor (MID) (continued) 



Field 



Length in Bytes Type of Data 



Description 



Map name 



Character 



Value for MFS 
COND parameter 
from the MID of a 
deferred 

program-to-program 
message switch 



Additional 
VisualAge Generator 
Server for MVS, 
VSE, and VM fields 



51 



Variable 



A group of fields 
that are used by 
VisualAge Generator 
Server for MVS, 
VSE, and VM to 
validate the map. 

Note: The total 
length of all fields 
prior to the start of 
the program map 
fields is 72 bytes. 



Program map fields 



Variable 



Variable 



This area contains 
the fields defined 
for the VisualAge 
Generator map 



Figure 52 on page 450 shows the COBOL definition for a map message input 
descriptor (MID) for a deferred program-to-program message switch. 
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COBOL Declare for a Map Message Input Descriptor (MID) 



* Copy Member ELAAHMMI 
01 EZEMAP-IO-AREA. 
05 EZEMAP-HEADER. 
10 EZEMAP-LL 
10 EZEMAP-ZZ 
15 EZEMAP-Z1 
15 EZEMAP-Z2 
10 EZEMAP-ZZ-BIN 

10 EZEMAP-MID-TRANCODE. 
15 EZEMAP-MOD-MAP 

10 FILLER 

10 EZEMAP-MOD-TRANCODE. 
15 EZEMAP-MID-MAP 

10 EZEMAP-STRUCTURE-TYPE 
88 EZEMAP-IS-A-MAP 

10 EZEMAP-SCA 

10 EZEMAP-SCA-BIN 

10 EZEMAP-EZEAID 

10 EZEMAP-HELP-PF-KEY 

10 EZEMAP-BYPASS-PF-KEYS. 
15 EZEMAP-BYPASS-PF-KEY 

10 EZEMAP-HELP-MAP-NAME 

10 EZEMAP-CURSOR. 
15 EZEMAP-ROW 
15 EZEMAP-COL 

10 EZEMAP-GEN-DATE-TIME. 
15 EZEMAP-DATE 
15 EZEMAP-TIME 

10 EZEMAP-SSM-STATUS-ATTR 
88 EZEMAP-SSM-PREMODIFIED 



PIC S9(4) COMP. 

PIC X(l). 
PIC X(l). 

REDEFINES EZEMAP-ZZ 
PIC S9(4) COMP. 

□ 

PIC X(8). 
PIC X(l). 

PIC X(8). 

PIC X(4). 
VALUE "MAP ". 

PIC X(2). Q 
REDEFINES EZEMAP-SCA 
PIC S9(4) COMP. 

PIC X(2). 
PIC X(2). 



10 EZEMAP-SSM-STATUS 
88 EZEMAP-SSM-INVALID 
88 EZEMAP-SSM-WSR-SAVED 
88 EZEMAP-SSM-WSR-MAP-SAVED VALUE "D". 
88 EZEMAP-SSM- FILL-CHAR VALUE X"FF" 



PIC X(2) 
OCCURS 5 TIMES. 

PIC X(8). 



PIC S9(4) COMP. 
PIC S9(4) COMP. 

PIC X(8). 
PIC X(8). 

PIC X(2). Q 
VALUE X"0081". 

PIC X(l). Q 
VALUE X"40" X"FF" 
VALUE "C". 



X"0O" 



* Copy Member For Map Group mapgroup 



01 EZEMFS-map 

05 EZEMFS-map-HEADER 
05 EZEMAP-DATA. 
10 mapitem. 
15 EZEATTR 
15 EZEDATA 



REDEFINES EZEMAP-IO-AREA. 
PIC X(72). Q 



PIC X(08) . 
PIC .... □ 



450 VisualAge Generati 
° Figure : 



eclare for a Map Message Input Descriptor (MID) 



Notes on Figure 52 on page 450 follow: 

Number 

Explanation or Comment 

Q For a MOD, the transaction name and the map name are reversed. If a 
conversational transaction is started by using an IMS /FORMAT 
command, IMS removes the transaction name from the data stream. 

Q In a MID, SCA is set to blanks. In a MOD, SCA must be initialized to 
binary zeros by the program that inserts the MOD. 

□ In a MOD, the EZEAID fields through the EZEMAP-GEN-DATE- 

TIME fields can be left blank. Any value placed in these fields is not 
returned on input. 

Q The transferring program must set EZEMAP-SSM-PREMODIFIED to 
TRUE to ensure that the value of EZEMAP-SSM-STATUS is 
transmitted to the transferred-to program. 

H If the transferring program leaves data in the work database for the 
transferred-to program to use in initializing its primary working 
storage record, it should use the level 88 EZEMAP-SSM-WSR-SAVED 
to set this field. Otherwise, this field should be initialized using the 
level 88 EZEMAP-SSM-INVALID. 

The transferred-to program should test the value of 
EZEMAP-SSM-STATUS to determine if there is data in the work 
database to restore. If either EZEMAP-SSM-WSR-SAVED or 
EZEMAP-SSM-WSR-MAP-SAVED is true, there is a working storage 
record in the work database to restore. 

H Map is the actual name of the map defined in VisualAge Generator or 
the name of the alias name if one had to be assigned. 

H Mapitem is the actual name of an item defined on the map or the alias 
name if one had to be assigned. If the mapitem is an array, an 
OCCURS clause is used. 

fl The PIC representation varies based on the type and length of the 
map item. 



VisualAge Generator Developer generates a COBOL copybook of the 

MID /MOD associated with a map group. The name of the copybook part is 

the map group name. The non- VisualAge Generator program can use this 

copybook to correctly define the message format that the VisualAge Generator 

program needs in the First Map and the message format received when a 

VisualAge Generator program transfers control to a non- VisualAge Generator 

program. 
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SPA Size and Working Storage Size 

Table 25 defines how the SPA and working storage are related for 
conversational processing. 



Table 25. Relationship of IMS SPA to Working Storage 



Function 


Spa Size versus 
Working Storage Size 


Results 


XFER 


SPA size exceeds size of 
VisualAge Generator record 
named in the XFER. 


SPA is created using the entire 
VisualAge Generator record, and 
the remaining bytes of SPA are 
initialized to blanks. 


XFER 


SPA size is less than size of 
VisualAge Generator record 
named in the XFER. 


Extra bytes of the VisualAge 
Generator record are truncated. 


Initialization of 
primary 

working storage 
record 


SPA size exceeds size of 
VisualAge Generator record 
named as primary working 
storage record for program. 


Extra bytes of the SPA are 
truncated when it is moved into 
the primary working storage 
record. 


Initialization of 
primary 

working storage 
record 


SPA size is less than size of 
VisualAge Generator record 
named as primary working 
storage record for program. 


Primary working storage record 
is initialized from the SPA, and 
the remaining bytes of the 
working storage record are 
initialized based on the data 
type. 



Conversational Immediate Program-to-Program Message Switch 

Conversational immediate program-to-program message switches are 
supported as follows: 

• Between two generated programs 

• From a non- VisualAge Generator program to a generated program 

• From a generated program to a non- VisualAge Generator program. 

Immediate Switch between Two Generated Programs: With this technique, 
two segmented conversational VisualAge Generator programs can change 
both the transaction name and the PSB name without presenting a map to the 
program user. Different map groups can be used by the two programs. 
Figure 53 on page 453 shows a skeleton definition of the two programs. 
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Immediate Switch between Segmented Conversational Programs 
Program A: 

Program Program Type= Main Transaction 

Specification: PSB Name = psbla 

Map Group = mapgpx 

Working Storage = wsrcdl 

Execution Mode = Segmented 



Process 
Definition: 



MOVE 'trxlb' to EZEAPP; 
XFER EZEAPP wsrcdl; 



Generation /SPA > G (Conversational) 

Opti ons : 

Program B: 

Program Program Type= Main Transaction 

Specification: PSB Name = psblb 

Map Group = mapgpy 

Working Storage = wsrcdl 
First Map = map2 (optional) 

Execution Mode = Segmented 

Process ("converses" map2, if specified) 

Definition: (initializes wsrcdl) 

(performs edits for map2, if specified) 



Generation /SPA > G (Conversational) 

Opti ons : 



Figure 53. Immediate Switch between Segmented Conversational Programs 

The program control logic automatically handles the SPA and the working 
storage record for both programs A and B. The SPA sizes for programs A and 
B must be at least large enough to hold the larger of the working storage 
records involved. 

Immediate Switch from non-VisualAge Generator Program to Generated 
Program: The non-VisualAge Generator program must be an IMS 
conversational program. The VisualAge Generator program must be defined 
like program B in the previous example. The /SPA generation option must 
specify the SPA size that is being used by the non- VisualAge Generator 
program. 

The non- VisualAge Generator program must do the following: 

1 . Create the SPA in the format defined in "Segmented Conversational 
Transaction SPA" on page 446. The data area in the SPA must match the 
working storage definition in the VisualAge Generator program. The 
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program control logic removes the header information (length, SPA ID, 
transaction name), so the VisualAge Generator program receives only the 
data. 

Note: If you specified /SPA=n„position as a generation option, the 

segmentation status byte is at the end of the SPA, regardless of the 
value of position. The non- VisualAge Generator program should 
initialize the segmentation status byte to blank before inserting the 
SPA. 

2. Insert the SPA to an alternate PCB. The alternate PCB must have its 
destination set to the transaction name for the VisualAge Generator 
program. 

Immediate Switch from Generated Program to non- VisualAge Generator 
Program: The non- VisualAge Generator program must be an IMS 
conversational program. The VisualAge Generator program must be defined 
like program A in the previous example. The /SPA generation option must 
specify the SPA size that is being used by the non- VisualAge Generator 
program. 

The non- Visual Age Generator program must issue a get unique to the I/O 
PCB to read the SPA. See "Segmented Conversational Transaction SPA" on 
page 446 for the required layout of the SPA. The SPA is created by the 
program control logic. The data area of the SPA contains the record that the 
VisualAge Generator program passed on the XFER. 

Note: If you specified / SPA=n„position as a generation option, the 

segmentation status byte is at the end of the SPA, regardless of the 
value of position. The non- VisualAge Generator program should ignore 
the last byte of the SPA. 

Conversational Deferred Program-to-Program Message Switch 

Conversational deferred program-to-program message switches are supported 
as follows: 

• Between two generated programs 

• From a non- VisualAge Generator program to a generated program 

• From a generated program to a non- VisualAge Generator program. 

Deferred Switch between Two Generated Programs: With this technique, 
two segmented conversational VisualAge Generator programs can change 
both the transaction name and the PSB name when a map is presented to the 
program user. You must use the same map group for both programs. You do 
not have to transfer a record, but a map is required. Figure 54 on page 455 
shows a skeleton definition of the two programs. 
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Deferred Switch between Segmented Conversational Program 
Program A: 

Program Program Type= Main Transaction 

Specification: PSB Name = psb2a 

Map Group = mapgp2 

Working Storage = wsrcd2 
Execution Mode = Segmented 



Process 
Definition: 



MOVE 'trx2b' to EZEAPP; 
XFER EZEAPP wsrcd2,map2; 



Generation /SPA > G (Conversational) 

Opti ons : 

Program B: 

Program Program Type= Main Transaction 

Specification: PSB Name = psb2b 

Map Group = mapgp2 

Working Storage = wsrcd2 

First Map = map2 

Execution Mode = Segmented 

Process (reads map2) 

Definition: (initializes wsrcd2) 

(performs map edits) 



Generation /SPA > 0 (Conversational 

Opti ons : 



Figure 54. Deferred Switch between Segmented Conversational Program 

Deferred Switch from non-VisualAge Generator Program to Generated 
Program: The non-VisualAge Generator program must be an IMS 
conversational program. The VisualAge Generator program must be defined 
like program B in the previous example. The /SPA generation option must 
specify the SPA size that is being used by the non- VisualAge Generator 
program. 

The non- VisualAge Generator program must do the following: 

1 . Create the SPA in the format defined in "Segmented Conversational 
Transaction SPA" on page 446. The data area in the SPA must match the 
working storage definition in the VisualAge Generator program. The 
program control logic removes the header information (length, SPA ID, 
transaction name), so the VisualAge Generator program receives only the 
data. 
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Note: If you specified /SPA=n„position as a generation option, then you 
must initialize the segmentation status byte at the offset within the 
SPA specified by position. Initialize the segmentation status byte to 
blank. 

2. Insert the SPA to the I/O PCB. 

3. Insert the map to the I/O PCB using the message output descriptor that 
corresponds to the message input descriptor in the VisualAge Generator 
program. The non- VisualAge Generator program must set the modified 
data tag (MDT) attribute for all variable data fields on the map to be 
passed to the VisualAge Generator program on the deferred switch. All 
other attributes should be left at their default values. See "VisualAge 
Generator Main Transaction MFS MID Format" on page 448 for the 
required layout of the map. The VisualAge Generator Developer creates a 
COBOL copybook for the MID/ MOD record layout that should be used by 
the non- VisualAge Generator program to ensure that the record formats 
match. 

Deferred Switch from Generated Program to non- VisualAge Generator 
Program: The non- VisualAge Generator program must be an IMS 
conversational program. The VisualAge Generator program must be defined 
like program A in the previous example. The VisualAge Generator program 
must set the MDT attribute on for all variable data fields that are required as 
input in the non- VisualAge Generator program. The /SPA generation option 
must specify the SPA size that is being used by the non- VisualAge Generator 
program. 

The non- VisualAge Generator program must do the following: 

1 . Issue a get unique to the I/O PCB to read the SPA. See "Segmented 
Conversational Transaction SPA" on page 446 for the required layout of the 
SPA. The SPA is created by the program control logic. The data area of the 
SPA contains the record that the VisualAge Generator program passed on 
the XFER. 

Note: If you specified /SPA=n„position as a generation option, the 

segmentation status byte is at the offset within the SPA specified by 
position. The non- VisualAge Generator program should ignore the 
value of the segmentation status byte. 

2. Issue a get next to the I/O PCB to retrieve the message input descriptor 
that corresponds to the message output descriptor used by the VisualAge 
Generator program. See "VisualAge Generator Main Transaction MFS MID 
Format" on page 448 for the required layout of the map. The VisualAge 
Generator Developer creates a COBOL copybook for the MID /MOD 
record layout that should be used by the non- VisualAge Generator 
program to ensure that the record formats match. 
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3. Use the value of the map MID field EZEMAP-SSM-STATUS to determine 
whether there has been a map integrity problem. If EZEMAP-SSM-FILL- 
CHAR is true and this is not an initial SPA (that is, not the first transaction 
in the conversation), then an input map integrity problem has occurred, 
possibly because the program user has pressed PA1 or PA2. Take whatever 
action is appropriate for the program to recover the data that was lost 
from the input map. This might involve issuing an error message to the 
program user and restarting the transaction or taking other recovery 
actions depending on the program design. 

Transferring with Segmented or Single-Segment Nonconversational 
Program 

Developing VisualAge Generator programs using single-segment mode differs 
from developing segmented programs as follows: 

• The program must save all information that is required to resume 
processing after a program user responds to the program. This type of 
program is more difficult to code, however is enables you to minimize the 
amount of data that is saved. 

• CONVERSE is not supported. First Map and XFER with a map are the only 
support provided for terminal maps. 

While the development of single segment programs is very different from that 
of segmented programs, the transferring process is the same as that used by 
segmented nonconversational programs. 

The same MID and MOD definitions are used for conversational and 
nonconversational transfers. Depending on the type of XFER statement used, 
the following can be passed on a transfer between two nonconversational 
programs: 

• An IMS message segment. See "VisualAge Generator Main Transaction 
Input Message Segment Format for Nonconversational Immediate Message 
Switch". 

• An MFS map. See "VisualAge Generator Main Transaction MFS MID 
Format" on page 448 for the record layout and an example of the COBOL 
definition for a map message input descriptor (MID) for a deferred 
program-to-program message switch. 

VisualAge Generator Main Transaction Input Message Segment Format 
for Nonconversational Immediate Message Switch 

Table 26 on page 458 shows the record layout for a working storage record 
passed as a message segment for an immediate program-to-program message 
switch: 
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Table 26. VisualAge Generator Main Transaction Input Message Segment Format for 
Nonconversational Immediate Message Switch 



Field 


Length in Bytes 


Type of Data 


Description 


Segment length 


2 


Binary 


The length of the 
segment 


Reserved 


2 


Binary 


Reserved for IMS 
use 


IMS transaction 
name 


8 


Character 


The IMS transaction 
name for the 
VisualAge Generator 
program 


Program working 
storage 


Variable 


Variable 


This area contains 
the fields defined 
for the VisualAge 
Generator working 
storage area. 


Figure 55 shows the COBOL definition for a working 


storage record passed 



via the message queue for an immediate program-to-program message switch. 
Gl CSP-APPL-WS-RECORD. 



05 


CSP-IMS-SEG-LENGTH 


PIC 


S9(4) 


COMP. 


05 


CSP-ZZ 


PIC 


S9(4) 


COMP. 


05 


CSP-IMS-TRANNAME 


PIC 


X(8). 




05 


CSP-APPL-WS-DATA. 








10 


<data-i tem-l> 


PIC 






10 


<data-item-2> 


PIC 







Figure 55. COBOL Declare for Working Storage Record Transferred via Message Queue 

Figure 56 shows the COBOL definition for a working storage record passed 
via the work database for a deferred program-to-program message switch. 

Ql CSP-APPL-WS-RECORD. 
G5 CSP-APPL-WS-DATA. 

1G <data-item-l> PIC 

1Q <data-item-2> PIC 

Figure 56. COBOL Declare for a Working Storage Record Transferred via the Work Database. 

Nonconversational Immediate Program-to-Program Message Switch 

Nonconversational immediate program-to-program message switches 
supported are as follows: 

• Between two generated programs 

• From a non- VisualAge Generator program to a generated program 
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From a generated program to a non-VisualAge Generator program. 



Immediate Switch between Two Generated Programs: When developing 
VisualAge Generator programs, this technique is the same as transferring with 
segmented conversational VisualAge Generator programs, except that the 
/SPA generation option is set to 0 (nonconversational). With this technique 
two nonconversational VisualAge Generator programs can change both the 
transaction name and the PSB name without presenting a map to the program 
user. Different map groups can be used by the two programs. Figure 57 shows 
a skeleton definition of the two programs. 

Immediate Switch between Segmented Nonconversational Programs 

Program A: 

Program Program Type= Main Transaction 

Specification: PSB Name = psbla 

Map Group = mapgpx 

Working Storage = wsrcdl 

Execution Mode = Segmented or Single Segment 



Process 
Definition: 



MOVE 'trxlb' to EZEAPP; 
XFER EZEAPP wsrcdl; 



Generation /SPA = G (Nonconversational) 

Opti ons : 

Program B: 

Program Program Type= Main Transaction 

Specification: PSB Name = psblb 

Map Group = mapgpy 

Working Storage = wsrcdl 

First Map = map2 (optional) 

Execution Mode = Segmented or Single Segment 

Process ("converses" map2, if specified) 

Definition: (initializes wsrcdl) 

(performs edits for map2, if specified) 



Generation /SPA = 0 (Nonconversational 

Opti ons : 



Figure 57. Immediate Switch between Segmented Nonconversational Programs 
Note: For better performance, omit First Map for program B. 

The program control logic automatically handles the IMS message that is used 
to transfer control and the working storage record from program A to B. 
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Either program A or B can be a single segment program. If program A or B is 
a segmented nonconversational program, it must have a /SPA generation 
option of 0. 

Immediate Switch from non-VisualAge Generator Program to Generated 
Program: The non-VisualAge Generator program must be an IMS 
nonconversational program. The VisualAge Generator program must be 
defined like program B in the previous example. 

The non- VisualAge Generator program must insert a message to an alternate 
PCB, The destination must be set to the transaction name for the VisualAge 
Generator program. See "VisualAge Generator Main Transaction Input 
Message Segment Format for Nonconversational Immediate Message Switch" 
on page 457 for the required layout of the message. The program control logic 
automatically removes the header information (length, ZZ, and transaction 
name), so the VisualAge Generator program defines only the data. However, 
the non- VisualAge Generator program must supply the header information. 

Immediate Switch from Generated Program to non- VisualAge Generator 
Program: The non- VisualAge Generator program must be an IMS 
nonconversational program. The VisualAge Generator program must be 
defined like program A in the previous example. 

The non- Visual Age Generator program must issue a get unique to the I/O 
PCB to retrieve the working storage record saved by the VisualAge Generator 
program. See "VisualAge Generator Main Transaction Input Message Segment 
Format for Nonconversational Immediate Message Switch" on page 457 for the 
required layout of the message. The program control logic automatically 
supplies the header information (length, ZZ, transaction name), so the 
VisualAge Generator program defines only the data. However, the 
non- VisualAge Generator program must be prepared to accept the header 
information. 

Nonconversational Deferred Prog ram-to-Prog ram Message Switch 

Nonconversational deferred program-to-program message switches are 
supported as follows: 

• Between two generated programs 

• From a non- VisualAge Generator program to a generated program 

• From a generated program to a non- VisualAge Generator program. 

Deferred Switch between Two Generated Programs: From a VisualAge 
Generator developer's viewpoint, this technique is identical to transferring 
with segmented conversational VisualAge Generator programs, except that the 
/SPA generation option is set to 0, meaning nonconversational. With this 
technique two nonconversational VisualAge Generator programs can change 
both the transaction name and the PSB name when a map is presented to the 
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program user. You must use the same map group for both programs. You do 
not have to transfer a record, but a map is required. Figure 58 shows a 
skeleton definition of the two programs. 

Switch between Segmented Nonconversational Programs 

Program A: 

Program Program Type= Main Transaction 

Specification: PSB Name = psb2a 

Map Group = mapgp2 

Working Storage = wsrcd2 

Execution Mode = Segmented or Single Segment 



Process 
Definition: 



MOVE 'trx2b' to EZEAPP; 
XFER EZEAPP wsrcd2,map2; 



Generation /SPA = G (Nonconversational) 

Opti ons : 

Program B: 

Program Program Type= Main Transaction 

Specification: PSB Name = psb2b 

Map Group = mapgp2 

Working Storage = wsrcd2 

First Map = map2 

Execution Mode = Segmented or Single Segment 

Process (reads map2) 

Definition: (initializes wsrcd2) 

(performs map edits) 



Generation /SPA = 0 (Nonconversational 

Opti ons : 



Figure 58. Deferred Switch between Segmented Nonconversational Programs 

Deferred Switch from non-VisualAge Generator Program to Generated 
Program: The non-VisualAge Generator program must be an IMS 
nonconversational program. The VisualAge Generator program must be 
defined like program B in the previous example. 

The non- VisualAge Generator program must do the following: 

1 . If a record is being transferred, call ELATSPUT to save the working 
storage record in the work database for the VisualAge Generator program. 
See "Writing To Work Database (ELATSPUT)" on page 463 for details on 
using ELATSPUT. 

2. Insert the map to the I/O PCB using the message output descriptor that 
corresponds to the message input descriptor used by the VisualAge 
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Generator program. The non-VisualAge Generator program must set the 
modified data tag (MDT) attribute for all variable data fields on the map 
to be passed to the VisualAge Generator program on the deferred switch. 
All other attributes should be left at their default values. See "VisualAge 
Generator Main Transaction MFS MID Format" on page 448 for the 
required layout of the map. The VisualAge Generator Developer creates a 
COBOL copybook for the MID/ MOD record layout that should be used by 
the non-VisualAge Generator program to ensure that the record formats 
match. 

Deferred Switch from Generated Program to non- VisualAge Generator 
Program: The non- VisualAge Generator program must be an IMS 
nonconversational program. The VisualAge Generator program must be 
defined like program A in the previous example. The VisualAge Generator 
program must set the MDT attribute on for all variable data fields on the map 
that are needed as input in the non- VisualAge Generator program. 

The non- VisualAge Generator program must do the following: 

1 . Issue a get unique to the I/O PCB to retrieve the message input descriptor 
that corresponds to the message output descriptor used by the VisualAge 
Generator program. See "VisualAge Generator Main Transaction MFS MID 
Format" on page 448 for the required layout of the map. The VisualAge 
Generator Developer creates a COBOL copybook for the MID /MOD 
record layout that should be used by the non- VisualAge Generator 
program to ensure that the record formats match. 

2. If working storage is needed, call ELATSGET to retrieve the working 
storage record saved by the VisualAge Generator program in the work 
database. See "Reading from Work Database (ELATSGET)" on page 463 for 
details on using ELATSGET. 

Using the VisualAge Generator Server for MVS, VSE, and VM Work 
Database 

VisualAge Generator programs can pass both a map and a working storage 
record for a deferred program-to-program message switch. When the 
segmented or single-segment program is generated as nonconversational, the 
work database is used to save working storage when an XFER statement 
specifies both a map and a record. VisualAge Generator Server for MVS, VSE, 
and VM provides subroutines that can be used by a non- VisualAge Generator 
program to store or retrieve data from the work database. Both the 
transferred-from and transferred-to programs or programs must use the same 
physical work database. 

The two service routines that non- VisualAge Generator programs can use to 
interface to the work database are: 

• ELATSGET to retrieve data from the work database. 
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• ELATSPUT to store data into the work database. 
Reading from Work Database (ELATSGET) 

ELATSGET reads a working storage record from the work database after a 
deferred program switch from a VisualAge Generator program. The logical 
terminal identifier is used as the work database key. 

The ELATSGET module is dynamically loaded in the following invocation 
sequence at run time. This method avoids having to link this module for each 
program that uses it. 
MOVE "ELATSGET" TO modname. 

CALL modname USING parml, parm2, parm3, parm4, parm5, parm6. 

In the previous example, modname is an 8-byte character field, and parml 
through parm6 are as follows: 
Record buffer 

Length of buffer (fullword binary) 

Transferred-to transaction code (8 bytes padded with blanks) 
I/O PCB 

ELAWORK PCB (or fullword of binary zeros if a DB2 work database is 
used) 

Return code (fullword binary). 

ELATSGET returns the following return codes: 

Code Meaning 

0 Read successful 

4 Read successful, truncation occurred 

8 Read failed, record not found 

12 Read failed, other error. 

Truncation occurs when the calling program attempts to restore into a buffer 
that is smaller than the data that was previously saved. If the buffer is larger 
than the data that was previously saved, the trailing portion of the buffer is 
initialized to blanks. 

ELATSGET does not issue any error messages. The calling program must take 
the appropriate action when an error occurs. If a DL/I work database is used, 
the PCB contains the status code that indicates the error. If a DB2 work 
database is used, the full-word binary (5th parameter) contains the SQL code 
that indicates the error. 

Writing To Work Database (ELATSPUT) 

ELATSPUT writes a working storage record to the work database before it 
performs a deferred program switch to a VisualAge Generator program. The 
logical terminal identifier is used as the work database key. 
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The ELATSPUT module is dynamically loaded in the following invocation 
sequence at run time. This method avoids having to link this module for each 
program that uses it. 
MOVE "ELATSPUT" TO modname. 

CALL modname USING parml, parm2, parm3, parm4, parm5, parm6. 

In the previous example, modname is an 8-byte character field, and parml 
through parm6 are as follows: 
Record buffer 

Length of record (fullword binary) 

Transferred-to transaction code (8 bytes padded with blanks) 
I/O PCB 

ELAWORK PCB (or fullword of binary zeros if a DB2 work database is 
used) 

Return code (fullword binary). 

ELATSPUT returns the following return codes: 
Code Meaning 

0 Write successful, new record added 

4 Write successful, existing record replaced 

12 Write failed, other error. 

ELATSPUT does not issue any error messages. The calling program must take 
the appropriate action when an error occurs. If a DL/I work database is used, 
the PCB contains the status code that indicates the error. If a DB2 work 
database is used, the fullword binary (5th parameter) contains the SQL code 
that indicates the error. 

Interfacing through Serial Files 

VisualAge Generator programs can interface with non-VisualAge Generator 
programs by adding or scanning records in serial files that are associated with 
the IMS message queue. 

Between Generated Programs 

A VisualAge Generator program can ADD a series of serial records to the IMS 
message queue by specifying the following: 

• The file is a message queue 

• The PCB number to be used 

A VisualAge Generator batch program, running as either an MPP or a 
transaction-driven BMP, can then SCAN the file to read the messages. The 
generated program automatically handles the IMS header information 
(segment length, ZZ, and transaction name). The transaction name is created 
from the default resource association specified in the Resource Allocation file 
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or on the value the EZEDEST special function word if it is used to override 
the default. Do not include IMS header information in the VisualAge 
Generator serial record definition. 

From non-VisualAge Generator Program to Generated Program 

A non- VisualAge Generator program can write a series of records to the IMS 
message queue for later processing by a VisualAge Generator batch program, 
running as either an MPP or a transaction-driven BMP. The non- VisualAge 
Generator program must insert a record in the format shown in Table 27 to an 
alternate I/O PCB associated with the transaction that processes the record. 



Table 27. Format of Record Inserted to Message Queue 



Field 


Length in Bytes 


Type of Data 


Description 


Segment length 


2 


Binary 


The length of the 
segment 


Reserved (ZZ) 


2 


Binary 


Reserved 


IMS transaction 
name 


8 


Character 


The IMS transaction 
name for the 
VisualAge Generator 
program 


Program-defined 
fields 


Variable 


Variable 


This area contains 
the data items 



defined in the serial 
record using 
VisualAge Generator 
record definition. 



A VisualAge Generator batch program that scans a serial file associated with 
the I/O PCB can process the message. The IMS message header (segment 
length, ZZ, and transaction name) is automatically removed by the generated 
program, so the VisualAge Generator program receives only the message data. 

From Generated Program to non-VisualAge Generator Program 

When a VisualAge Generator program does an ADD to a serial file associated 
with a message queue, the generated program automatically adds the IMS 
message header in front of the record data, and then inserts the message to 
the alternate PCB. The VisualAge Generator program is only concerned with 
the actual data in the message. 

A non- VisualAge Generator program running as either an MPP or a 
transaction-driven BMP can process the queue. The format of the message 
actually inserted to the message queue and received by the non- VisualAge 
Generator program is shown in the Format of the Record Inserted to the Message 
Queue table in "From non- VisualAge Generator Program to Generated 
Program". 
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Interfacing with IMSADF II Programs 

Generated VisualAge Generator programs can also transfer to or from 
IMSADF programs. Immediate program-to-program message switches can be 
performed between IMSADF II conversational programs and VisualAge 
Generator segmented conversational programs running with the ADF 
parameter on the /SPA generation option. In addition, IMSADF II secondary 
transactions can be processed by VisualAge Generator batch programs. 

Notes: 

1 . Because of differences in the way VisualAge Generator and IMSADF II 
programs pass the PCB information, VisualAge Generator cannot be used 
to write IMSADF II special processing routines. Because of differences in 
map layout conventions, deferred program-to-program message switches 
between IMSADF II and VisualAge Generator programs are not supported. 

2. Different considerations apply for transferring between VisualAge 
Generator programs when IMSADF II programs are involved. Both 
VisualAge Generator programs involved in a transfer must either omit the 
ADF parameter for the / SPA generation option, or both programs must 
include the ADF parameter. 

IMSADF II Conversational Processing 

VisualAge Generator cannot be used to initiate IMSADF II, but can be used to 
receive control from and return control to the IMSADF II transaction driver. 
This is supported only when the IMSADF II program system uses the 
IMSADF II 28-byte SPA with a work database. 

VisualAge Generator Developer provides a sample DL/I record definition for 
the IMSADF II, Version 2, Release 2, work database in external source format 
as part EZERWADF.ESF in the default external source format directory, 
C:\VAST\SAMPLES. The record name is ADFWKDB. The fields in this 
definition are limited to those you must modify if a VisualAge Generator 
program is transferring directly to the IMSADF II conversational transaction 
driver. 

Note: The work databases for IMSADF II and VisualAge Generator Server for 
MVS, VSE, and VM are NOT shared. They have different formats. 
Changes to the IMSADF II work database do not affect the work 
database for VisualAge Generator Server for MVS, VSE, and VM. 
Similarly, changes made by a VisualAge Generator program to the 
work database for VisualAge Generator Server for MVS, VSE, and VM 
do not affect the IMSADF II work database. 

Starting from the IMSADF II side, define the VisualAge Generator program to 
IMSADF II in the same way that you define a transaction that is written 
entirely in COBOL. Refer to the IMSADF II documentation for your system 
for additional information. 
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The VisualAge Generator program name (and therefore, the load module 
name) must follow the IMSADF II naming convention, as follows: 

ssssTcc 

where ssss is the IMSADF II program system ID, T is a constant, and cc is the 
cluster code (SOMTX) operand used to generate the transaction that causes 
the switch to the VisualAge Generator program. 

From IMSADF II Transaction Driver to VisualAge Generator Program 

When the program user enters the IMSADF II transaction ID that corresponds 
to the VisualAge Generator program, IMSADF II does an immediate 
program-to-program message switch to transaction ssssTcc. IMSADF II writes 
its own 28-byte SPA to the IMS message queue to perform the switch. 

The VisualAge Generator program must be generated with /SPA=28,ADF to 
match the IMSADF II SPA size. When IMS schedules the new transaction, the 
program control logic reads the IMSADF II SPA from the I/O PCB. Because of 
the /SPA=28,ADF option, the program control logic does not modify the SPA 
in any way. Therefore, the VisualAge Generator program can eventually do an 
immediate program-to-program message switch back to the IMSADF II 
conversational transaction driver. Switching directly to the IMSADF II sign-on 
transaction is not supported. 

If a series of VisualAge Generator programs are involved prior to transferring 
back to the IMSADF II conversational transaction driver, all the VisualAge 
Generator programs must be generated with /SPA=28,ADF. The program 
control logic uses the VisualAge Generator Server for MVS, VSE, and VM 
work database or a second message segment following the SPA to pass 
working storage records among the VisualAge Generator programs, thereby 
preserving the IMSADF II-formatted SPA. Both deferred and immediate 
program-to-program message switches can be used among the VisualAge 
Generator programs. 

Note: /SPA=28,ADF,position where position specifies an available byte in the 
IMSADF II SPA that can be used for VisualAge Generator's 
segmentation status byte is also a valid generation option. All 
VisualAge Generator programs involved in a series of message switches 
that started from the IMSADF II transaction driver must have the same 
/SPA generation option. Refer to your IMSADF II documentation for 
information on the positions in the SPA that are available. 

As in a COBOL program, the VisualAge Generator program can access the 
IMSADF II work database to use information or to modify information in the 
IMSADF II communication area. If the IMSADF II work database is accessed, 
the VisualAge Generator program processes the IMSADF II work database as 
any other program database. The sample IMSADF II work database 
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definitions provided by VisualAge Generator can be used by the program. If a 
DL/I IMSADF II work database is used, a DB PCB must be included in the 
VisualAge Generator PSB definition for it. 

From VisualAge Generator Program to IMSADF II Transaction Driver 

To switch back to the IMSADF II transaction driver, code the VisualAge 
Generator program to modify the IMSADF II work database to set flags 
indicating what the transaction driver is to do when it receives control. Refer 
to the IMSADF II documentation for your system for additional information. 
The VisualAge Generator program transfers control using an XFER statement 
and specifies no working storage record and no map. EZEAPP should be used 
for the XFER and must contain the same value that was placed in the 
IMSADF II variable SPATRANS. The program control logic inserts the SPA to 
cause an immediate program-to-program message switch back to IMSADF II. 

Transferring with Segmented Conversational Programs in ADF Mode 

Note: The techniques described in this section are used only when there is a 
transfer from IMSADF II to a series of VisualAge Generator programs 
and non- VisualAge Generator programs prior to transferring back to 
IMSADF II. If only a single VisualAge Generator program is used and 
then transfers back to IMSADF II, the program control logic 
automatically preserves the IMSADF II SPA. For transfers when 
IMSADF II is not involved, see "Transfers in the IMS MPP 
Environment" on page 442. 

Table 28 on page 469 shows the conventions used for transferring between 
VisualAge Generator programs when the ADF SPA option is in effect. It 
differs from the techniques used when IMSADF II is not involved, in that 
special techniques are used to pass working storage so the SPA can remain 
intact. Segmented nonconversational and single segment programs are not 
supported in ADF mode. 
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Table 28. Program Switching in VisualAge Generator Programs (IMSADF II Interface) 



Generation Option of 
Transferred-to Program 

Segmented conversational 
(ADF scratchpad area 
generation option- /SPA=28, 
ADF or /SPA=28, ADF, 
position, where position is 
between 15 and 28 and 
specifies the location of the 
segmentation status byte) 



Immediate Switch 
(Optional First Map) 

Define both programs as 
segmented. Generate both 
programs as conversational 
with the ADF SPA option. 

The transferring program 
cannot send a map. If it is a 
VisualAge Generator 
program, it transfers using 
an XFER with only a 
record. 



The transferred-to program 
can optionally have a First 
Map. 

The record is transferred in 
a message segment 
following the SPA. 

If position was specified,the 
transferred-to program 
always ignores the value of 
the segmentation status 
byte that is located in the 
SPA at the offset specified 
by position. 



Deferred Switch (with 
First Map) 

Define both programs as 
segmented. Generate both 
programs as conversational 
with the ADF SPA option. 

The transferring program 
must write the map to a 
message queue associated 
with the terminal after first 
writing the SPA. If it is a 
VisualAge Generator 
program, it does this using 
an XFER with a map and 
an optional record. 

The transferred-to program 
must have a First Map. 



The record, if any, is 
transferred through the 
work database. 

If position was specified, 
the transferred-to program 
uses the value of the 
segmentation status byte at 
the offset specified by 
position when there is an 
input map integrity 
problem caused by the 
program user pressing PA1 
or PA2. 



Note: The segmentation status byte specified by position is used only for program to 
program transfers for conversational programs. The byte is present for transfers 
between conversational programs and programs. However, a transferring 
non- VisualAge Generator program should always set the byte to blank. A 
transferred-to non- VisualAge Generator program can ignore the value of the 
segmentation status byte. 



Segmented Conversational Immediate Program-to-Program Message 
Switch between Two Generated Programs 

With this technique two segmented conversational VisualAge Generator 
programs can change both the transaction name and the PSB name without 
presenting a map to the program user. Different map groups can be used by 
the two programs. The Immediate Switch between Segmented Conversational 
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Programs figure in "Immediate Switch between Two Generated Programs" on 
page 452 shows a skeleton definition of the two programs, except that the 
ADF parameter must be included for the / SPA generation option. 

The program control logic automatically preserves the SPA and manages the 
working storage record as a message segment following the SPA for both 
programs A and B. The same SPA size (28 bytes) is used for both programs A 
and B. 

Segmented Conversational Immediate Program-to-Program Message 
Switch from non-VisualAge Generator Program to Generated Program 

The non-VisualAge Generator program must be an IMS conversational 
program. Define the VisualAge Generator program as Program B is defined in 
"Immediate Switch between Two Generated Programs" on page 452, except 
include the ADF parameter for the /SPA generation option. 

The non- VisualAge Generator program must be an IMS conversational 
program. 

The non- VisualAge Generator program must do the following: 

1 . Preserve the IMS ADF II SPA format. 

2. Insert the SPA to an alternate PCB, with the destination set to the 
transaction name for the VisualAge Generator program. 

Note: If you specified /SPA=28,ADF,position as a generation option, the 
segmentation status byte is in the SPA at the offset specified by 
position. Initialize the segmentation status byte to blank before 
inserting the SPA. 

3. Insert the working storage record as a message segment after the SPA into 
the same alternate PCB. See "VisualAge Generator Main Transaction Input 
Message Segment Format for Nonconversational Immediate Message 
Switch" on page 457 for the required layout of the message. 

Segmented Conversational Immediate Program-to-Program Message 
Switch from Generated Program to non-VisualAge Generator Program 

The non- VisualAge Generator program must be an IMS conversational 
program. Define the VisualAge Generator program as program A is defined in 
the Immediate Switch between Segmented Conversational Programs figure in 
"Immediate Switch between Two Generated Programs" on page 452, except 
include the ADF parameter for the / SPA generation option. 

The non- VisualAge Generator program must do the following: 

1 . Issue a get unique to the I/O PCB to read the SPA. This SPA is in the 
original IMSADF II format, unchanged by the VisualAge Generator 
program. 
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Note: If you specified / SPA=28,ADF,position as a generation option, the 
segmentation status byte is in the SPA at the offset specified by 
position. The non-VisualAge Generator program should ignore the 
value of the segmentation status byte. 

2. Issue a get next to the I/O PCB to read the message that contains the 
working storage record. See "VisualAge Generator Main Transaction Input 
Message Segment Format for Nonconversational Immediate Message 
Switch" on page 457 for the required layout of the message. 

3. Preserve the IMSADF II SPA format. 

Segmented Conversational Deferred Program-to-Program Message 
Switch between Two Generated Programs 

With this technique two segmented conversational VisualAge Generator 
programs can change both the transaction name and the PSB name when a 
map is presented to the program user. The same map group must be used by 
the two programs. You do not have to transfer a working storage record, but a 
map is required. A skeleton definition of the two programs is shown in the 
Deferred Sivitch between Segmented Conversational Programs figure in "Deferred 
Switch between Two Generated Programs" on page 454, except that you must 
include the ADF parameter for the /SPA generation option. 

Segmented Conversational Deferred Program-to-Program Message 
Switch from non-VisualAge Generator Program to Generated Program 

The non- VisualAge Generator program must be an IMS conversational 
program. Define the VisualAge Generator program as program B is defined in 
the Deferred Switch between Segmented Conversational Programs figure in 
"Deferred Switch between Two Generated Programs" on page 454, except 
include the ADF parameter for the /SPA generation option. 

The non- VisualAge Generator program must do the following: 

1 . Preserve the IMSADF II SPA format. 

Note: If you specified /SPA=28,ADF,position as a generation option, the 
segmentation status byte is in the SPA at the offset specified by 
position. Initialize the segmentation status byte to blank before 
inserting the SPA. 

2. Call ELATSPUT to save the working storage record for the VisualAge 
Generator program in the work database. See "Writing To Work Database 
(ELATSPUT)" on page 463 for details on using ELATSPUT. 

3. Insert the SPA to the I/O PCB. 

4. Insert the map to the I/O PCB using the message output descriptor that 
corresponds to the message input descriptor in the VisualAge Generator 
program. The non-VisualAge Generator program must set the modified 
data tag (MDT) attribute for all variable data fields on the map to be 
passed to the VisualAge Generator program on the deferred switch. All 
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other attributes should be left at their default values. See "VisualAge 
Generator Main Transaction MFS MID Format" on page 448 for the 
required layout of the map. The VisualAge Generator Developer creates a 
COBOL copybook for the MID/ MOD record layout that should be used by 
the non-VisualAge Generator program to ensure that the record formats 
match. 

Segmented Conversational Deferred Program-.to-Program Message 
Switch from Generated Program to non-VisualAge Generator Program 

The non- VisualAge Generator program must be an IMS conversational 
program. Define the VisualAge Generator program as program A is defined in 
the Deferred Sivitch between Segmented Conversational Programs figure in 
"Deferred Switch between Two Generated Programs" on page 454, except 
include the ADF parameter for the /SPA generation option. The VisualAge 
Generator program must set the MDT attribute on for all variable data fields 
on the map that are needed as input in the non- VisualAge Generator 
program. 

The non- VisualAge Generator program must do the following: 

1 . Issue a get unique to the I/O PCB to read the SPA. This SPA is in the 
original IMSADF II format, unchanged by the VisualAge Generator 
program. 

2. Issue a get next to the I/O PCB to retrieve the message input descriptor 
that corresponds to the message output descriptor used by the VisualAge 
Generator program. See "VisualAge Generator Main Transaction MFS MID 
Format" on page 448 for the required layout of the map. The VisualAge 
Generator Developer creates a COBOL copybook for the MID /MOD 
record layout that should be used by the non- VisualAge Generator 
program to ensure that the record formats match. 

3. Use the value of the map MID field EZEMAP-SSM-STATUS to determine 
whether there is a working storage record in the work database. 

• If either EZEMAP-SSM-WSR-SAVED or EZEMAP-SSM-WSR-MAP- 
SAVED is true, then there is a record in the work database. Retrieve it as 
described in step 4 below. 

• If EZEMAP-SSM-FILL-CHAR is true and this is not an initial SPA, then 
an input map integrity problem has occurred, probably because the 
program user has pressed PA1 or PA2. Take whatever action is 
appropriate for the program to recover the data that was lost from the 
input map. This might involve issuing an error message to the program 
user and restarting the transaction or other recovery actions depending 
on the program design. In this situation, if /SPA=28,ADF,position was 
specified as a generation option, the program can use the segmentation 
status byte to determine if a working storage record was saved in the 
work database prior to the transfer. If the segmentation status byte has 
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one of the following values: C, c, D, d then a working storage record 
was saved in the work database and you can retrieve it as described in 
step 4 below. 

4. Call ELATSGET to retrieve the working storage record saved by the 
VisualAge Generator program in the work database. See "Reading from 
Work Database (ELATSGET)" on page 463 for details on using ELATSGET. 

5. Preserve the IMSADF II SPA format. 
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